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!♦! WHAT THIS IS 



This package consists oft 

(a) the Coin-Op version of the FORTH programing language residing on the disk harked Atari Coin-Op 

FORTH* version l#4Vt 

(b) the source code for a number of programs in FORTH, to be found on the disks narked "Swarthmore 
l»t "Swarthmore 2", and "Swarthmore QE"* 

(c) Discussion and glossaries for all the above* 

All disks except QE boot to unadorned Coin-Op FORTH* QE boots to an embellished version 
described in the next section* 

Coin-Op FORTH was developed by Steve Calfee at Atari, Inc* and the disk enclosed is, except for 
3 V ery few minor changes, exactly what he has informally distributed* This is a well-wrought, tight 
version of FORTH* Among its notable features are an excellent compile time* The 32 line screens 
allow for writing clear code (see Section V* How to Write Good FORTH)* 

The Swarthmore disks contain programming tools which were developed over a two-year period by 
the Swarthmore Trigonometry Project* These range from simple aids for the beginning programmer to 
more sophisticated program development tools* He hope that the doojmentation will be of use to the 
corresponding range of programmers* In almost all cases, we provide a discussion of each FORTH word, 
along with the source code (except for much of the booted material on the Coin-Op disk)* 

Hhat this isn't 

This is not a complete FORTH tutorial - we recommend its use in conjunction with a standard 
FORTH text, such as Starting Forth * 

This is not a complete Atari tutorial - see the references in the next section* 

This is not a version of FORTH for all users* In particular, it lacks a floating-point 
arithmetic package (because floating-point arithmetic is much slower - see the discission in Chapter 
5 of Starting FORTH ) * In most instances, this should not be a disadvantage* 

The code is probably not error free - although we have tested arid used everything and know of no 
errors* (Until it is used for some time by a wide variety of users, most code is not error free)* 

The documentaton will not be perfect for everyone* At least we've worked hard to produce what 
we would have liked to receive ourselves* 



TO USE THXS MATERIAL 



Remove any cartridges from your Atari 100 or 800 , turn on the disk drive, insert the Atari 
Coin-Op disk, and turn on the computer. Unless your disk drive's speed is badly out of adjustment or 
Magnetic disaster has struck the disk, after a short tine you should get the message H f ig-FORTH 
it4v* M You are now in FORTH ♦ Feel free to play* The worst you can do (if your disk is write 
protected) is to crash the system, in which case try the Reset button, or for a high quality crash, 
reboot* 

■ Such discovery learning will not get you very far very fast or very thoroughly, arid we recommend 
you work along with a good text* Two sections hence, we chronicle the differences between Coin-Op 
FORTH and the FORTH referred to in the excellent text, Starting FORTH * You'll find our Glossary of 
the Coin-Op Kernel, Section 11*2, a handy companion. 

One of the first things you'll want to do is make a backup copy* If you have more than one disk 
drive, see section ITL2 on Disk Copy Routines, and proceed accordngly* Things are tougher if you 
only have one drive. See Section IEL1 HTOBJ to get a copy of the booted part of any disk, but 
transferring source screens is lengthy. To transfer two individual screens from a source disk to a 
destination disk, stick in the source disk and type the incantation*. 

1st .screen* number BLOCK DROP UPDATE [RETURN] 

2nd* screen* number BLOCK DROP UPDATE [RETURN] 
Then insert the destination disk and type FLUSH (and hit [RETURN]) ♦ Unfortunately, this won't work 
for more than two screens at a time. To see the screens before transferring them, replace BLOCK by 
LIST in the above. 

There are two changes in your programming environment you might want to make at first. Type 
1 WARNING ! [RETURN] 
to receive error messages rather than error numbers. (The error messages are on screens 2 through 
5). Coin-Op FORTH comes in hexadecimal. Typing DECIMAL will get you into what is likely to be a 
more familiar environment. However, hitting System Reset or rebooting will return you to hex. To 
create a disk which will boot to decimal (and stay there with System Reset), type 

' DECIMAL CFA ' ABORT 2+ ! [RETURN] 
Then do a HTOBJ (see Section HI#1) so that these changes will be made part of the boot. 

You might want to consider some further additions to your booted FORTH system. The followng 
seem particularly useful 5 Fast INDEX, $ (which causes the next number to be interpreted as 
hexadecimal), and the QE editor (which is large, but worth it, we think). All are in Section IV. 
After such additions are compiled, it is necessary to do a HTOBJ (Section III.l) to make them part of 
the boot* 

The Swarthmore QE disk boots with all these treats but without 1 WARNING !♦ However, the 
object code extends through screen 8, so you'll get crazy error messages with 1 WARNING ! unless you 
insert a disk which has them on screens 2-6. 

In using the documentation, we expect you to have certain references available. For the Atari, 
we assume you have a 400/800 Basic Refernce Manual, which comes with the computer. For deeper 
hardware questions, we sometimes refer to De Re Atari , by Chris Crawford, et al, Atari, Inc., 
1981,APX-90008. For matters pertaining to FORTH, we refer you to Starting FORTH, by Leo Brodie, 
Prentice-Hall, 1981. 

Sometime, please read Section How to Write Good FORTH* 




For the ft tar it 



Above arid beyond De Re Atari, you flight wish to consult the Atari 400/800 Hardware Manual or the 
Atari 400/800 Operating Systen User's Manual, available fron Atari, Inc* 



For FORTH: 



The following have proved useful* 

Glenn B« Haydon, All About FORTH, Mountain View Press, 1982* 
(Good glossary of words frOM several different FORTHs*) 



Mitch Derick t Linda Baker, FORTH Encyclopedia, Mountain View Press, 1982 « 
(More detailed than the above*) 



C#Hi Ting, Systems Guide to Fio FORTH , Offete Enterprises, Inc*, 1980* 
(Good for how FORTH works* ) 

Hillian F« Ragsdale, fig-FQRTH Irrstallation Manual , Forth Interest Group, 1980* 



All the above are available frort Mountain View Press, P*Q* Box 4656, Mountain View, Ca*, 94040, (415) 
961-4103* 

Serious FORTH users should consider joining the FORTH Interest Group* Their journal, FORTH 
Dimensions , nakes interesting reading* FORTH Interest Group, P*0* Box 1105, San Carlos, Ca* 94070* 
(415) 962-8653* 
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FORTHs based on the fig (FORTH Interest Group) Model, such as the CoirrOp FORTH kernel, are 
different in some significant ways from the version of FORTH described in Starting FORTH (which is 
nonetheless an excellent introductory text for the beginning Coin-Op FORTH user)* Following is a 
list, referenced by Starting FORTH page number, of words in Starting FORTH which either have 
different names or are not used at all in Coin-Op FORTH ♦ There are also a few notes included on more 
general differences between the two* This list of differences is fairly complete, but it should not 
be regarded as comprehensive* In particular, there are a nunber of words included in Coin-Op FORTH' s 
kernel which are not in Starting FORTH * and which are not Mentioned in the following list* These 
range from words used to manipulate headers (NFA, PFA, etc*) to disk buffer words (ELOCK, BUFFER) to 
words for listing the dictionary (MUST) ♦ After you are familiar with Starting FORTH , browse through 
the Coirr-Op FORTH glossary to become familiar with these words* 

ESi 19 - Coin-Op FORTH allows up to 31 characters of a name to be stored in the dictionary* 

PP« 57-58 - The fig-FORTH editor is very different from that described in Starting FORTH ? the 
Starting FORTH discussion of FORTH' s screen-based system will nonetheless be quite useful to the 
CoirrOp FORTH user* The following words are basically the same in Starting FORTH and Coin-Op FORTH** 
LIST, LOAD, (, FLUSH, COPY, FORGET* 

ESi 91 - The fig-FORTH word 0= takes the place of HOT in Coirr-Op FORTH* 
ESi 101 - The fig-FORTH word -DIP takes the place of ?DUP in Coin-Op FORTH* 
ESi 101 - AE£)RT H does not exist in Coin-Op FORTH* 

ESi 107 - The words 1- and 2* do not exist in fig-FORTH, but they are included as part of the Coin-Op 
FORTH boot* The words 2- and 2/ are included in neither fig-FORTH nor CoirrOp- FORTH* 

ESi M§ - In Coin-Op FORTH, NEGATE is called HINUS* 

ESi Hi - The word F does not exist in CoirrOp FORTH* 

ESi 132 - U*R does not exist in Coin-Op FORTH* 

ESi 139 - In addition to BEGIN *♦♦ UNTIL and BEGIN ♦** WHILE *** REPEAT, Coin-Op FORTH also supports 
BEGIN ♦♦♦ AGAIN, where AGAIN executes an unconditional branch back to BEGIN* 

ESi 132 - PAGE does not exist in CoirrOp FORTH* Clear ing the screen is performed by the Coin-Op 
FORTH word CLEAR* 

ESi 161 - The words U/MOD, U*, and /LOOP do not exist in Coin-Op FORTH* Coin-Op FORTH does include 
the word U/ (unsigned divided by), which is not included in Starting FORTH * 

ESi- 162 - The word OCTAL does not exist in Coin-Op FORTH. Octal can be set by the command 8 BASE ! * 

ESl • The only punctuation mark which may be used during input to indicate a double nunber is ♦ 
(period) ♦ 



T*4 Coin-Op FORTH vs« Starting FORTH, p »Z 

■ 



£0^. 173 - The double nuriber operators D-, DHAX, DMIN, D= t D0=, DC, and IXK do not exist in Coin-Op 
FORTH* The word DNEGATE has been replaced by the f ig-FORTH word DMINUS* Coin-Op FORTH includes the 
word Di which is not Mentioned in Starting FORTH . 

E£i 174 - M+ and W do not exist in Coin-Op FORTH* Coin-Op FORTH does include two nixed length 
operators, M/HOD and D8U*, which are not included in Starting FORTH * 

££*_ 183 - VARIABLE takes an argument on the stack in Coin-Op FORTH, arid stores this argument in the 
newly defined variable's parameter field* 

PQ, 193 * Double length variables and constants do not exist in Coin-Op FORTH** thus, 2VARIABLE, 
2C0NSTANT, 2!, and 26 are not defined* 

£2^ 205 - DUMP does not exist in Coin-Op FORTH* 

£2^ 217 - EXECUTE requires the CFA, not the PF A, of a word* Using the PFA will crash the system* 

E2*. 218 - t'1 is not defined in Coin-Op FORTH, since ' is defined as being immediate* Thus ' can be 
used in place of C' 3 in a colon definition* 

pp» 220-221 - The structure of Coin-Op FORTH headers is significantly different from that described 
in Starting FORTH * See the discussion of Coin-Op FORTH headers, linking and vocabularies* EXECUTE 
expects the CFA, not the PFA, of a word* 

do. 225 - The word EXIT is called }S in Coin-Op FORTH* 

£cu 233 - H is called DP in Coin-Op FORTH* 

ES*. 235 - 'S is called SPG in Coin-Op FORTH* 

236 - SO is not directly available to the user in Coin-Op FORTH* See the glossary entry for SO* 

pp. 232-233 - The Starting FORTH discussion of vocabularies applies quite well to Coin-Op FORTH, as 
far as it extends (the one exception is that 5 sets CONTEXT to CURRENT, not to FORTH)* The Coin-Op 
FORTH linking system is significantly different from other FORTHs, however, and this effects 
vocabularies. See discussion of linking arid vocabularies in Section XI tit 

22± 256 - FLUSH does not "forget" that a buffer is in memory in Coin-Op FORTH 1 , it only turns off the 
"updated" flag* 

£3*. 261 - >TYPE does not exist in Coin-Op FORTH* 

ES± 266 - MOVE and <CHDVE are not defined in Coin-Op FORTH* 

££♦_ 270 - WORD does not leave the address of HERE on the stack* TEXT does not take a delimiter on 
the stack? instead, it reads all characters up to the next carriage return* 

£□*, 272 - >IN is called IN in Coin-Op FORTH* 

£2_*_ 277 - BINARY ( CONVERT ) does not exist in Coin-Op FORTH* 

£^ 281 - -TEXT is not defined in Coin-Op FORTH* 

£2^ 291 - The word CREATE is called <BUILDS in Coin-Op FORTH* The Coin-Op FORTH word CREATE only 
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creates 3 header for new dictionary entries ♦ 



E2± 301 - Coin-Op FORTH uses (DO), not 2>R* 

ESt 303 - (LITERAL) is called LIT in Coin-Op FORTH. 






Coin— Qp FORTH Disk : 

Screens 2-5 Error Messages 

9 Screen originally used to compile assembler 

11 Disk copy routines CUL2) 

13-19 The Assembler (11*5) 

20 Undocumented 

21-25 The fig Editor (11*4) 

26 OS and Hardware constants (in Glossary , 11*2) 
27-29 Undocumented 

30 DECUS FORTH additions (in Glossary , II* 2) 

31 Display list disassembler, undocumented 
32-33 FORMAT and HTOBJ (m*l) 

35-36 Uridocumented 
37-38 Line Printer words (HM) 
39-^3 Formatted printer words (111*1) 
11-16 Undocumented 



Swarthnore Disk. ±t 

Screen 1 Directory 

2-5 Error messages 
7-17 IV* 1 Miscellaneous 
20 IV ,2 Fast INDEX 
22-23 IV. 3 CASE 



IM Display List assembler 
29 IV* 5 Cheap character generator 
31-31 IV* 6 String search 
37-18 IV*7 Print commands for graphics modes 
50-51 IV* 8 Screen copy routines 
53-55 IV*9 Vertical scrolling 



Swarthfiore D i sk 2* 

Screen 1 Directory 

2-5 Error messages 

10-13 IV* 10 Unshadowed Player Missile words 

15-20 IV* 11 Shadowed Player Missile words 

22-31 IV* 12 Text words for disk storage of text 

33-19 IV* 13 Text compression text words 

52-53 IV* 11 VBLAHK routines 

55-61 IV* 15 Big HTOBJ 




Su>3T"t,HfiPT"e QE Disk X 

Screens 0-8 Boot source code continuation 
11-77 Source code for QE (IV* 17) 

NOTE : The QE disk boot contains QE (and therefore the Miscellaneous words* CASE, Display List 
assembler, arid unshadowed Player Missiles)*, it also has Fast Index* It boots to decimal* 
All other disks boot to Coin-Op FORTH* 



INTRODUCTION 

The documentation of the Coin-Op FORTH hoot is divided into four parts, which correspond to the 
four sections of the hoot itself* These four sections incli.de: 

1) 3 modified f ig-FORTH kernel 

2) Atari graphics, sound t arid device control words arid a few other miscellaneous words 

3) a fig-FORTH editor 

4) a fig-FORTH assembler* 

The section on the Coin-Op FORTH kernel consists of a list of the modifications which have been 
made to the fig-FORTH model and brief discussions of the most important departure from that model 
(the vocabulary/linking system) and of the Atari-specific disk access words) these are followed by a 
complete glossary of the kernel* The discussion of each extension includes a brief discussion of how 
to use the important words in that exter»ion f followed by a complete glossary of the extension* 

11*1 THE FORTH KERNEL 

COIN-OP FORTH VS* FIG-FORTH 

■ ■ ■ ■ ■ ■ ' • ■ 

The Coin-Op FORTH kernel (i*e*, the 250 or so words which constitute the heart of FORTH) is 
based on fig-FORTH* However, a number of modifications have been made* These 3re listed below* for 
the convenience of those who are already familiar with fig-FORTH* (The sections on disk access and 
disk buffers* headers, links, arid vocabularies will also be of use to those who are not familiar with 
fig-FORTH*) 

The following fig-FORTH words are not included in Coin-Op FORTH* +BUF , BLOCK-READ , BLDCK-HRTTE 
, DUST (this word was used to list the vocabulary? it had nothing to do with graphics display 
lists), DUMP , HON , MOVE , USE ♦ 

The following words are included in the CoirrOp FORTH kernel but are not part of the fig-FORTH 
model (for explanations of their usage, see the Coin-Op Kernel Glossary*, in addition, some of these 
words will be discussed in more detail in the sections on disk access arid disk, buffers, headers, 
links, and vocabularies)** *LM(S , 7BITS , ALT , EfXD , D8U* , DDIO , DECMAP , DIO , FLUSH , HASH , 
HIMEM , ICAL , ICCM , ICLL , J , PHYSOFF , PTAB , SECIO , SIO , TCIOV , IK * 

Headers, Links, and Vocabularies 

Coin-Op FORTH executes dictionary searches much, much faster than standard fig-FORTH 4 , this in 
turn means that much less time is spent by the programmer in compiling FORTH words and screens* The 
vastly increased speed was obtained by modifications to the header structure of dictionary entries 
and by the introduction of "sub-vocabularies" ♦ Most users will not need to understand these 
differences in order to use FORTH to full advantage* Other users will require such an understanding, 
however, and still others will simply be interested in what makes FORTH tick* The following 
discussion should be helpful* 
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Headers 

Noma! fig-FORTH headers have the following structure* 
HFA 

a name field, starting at NFA, which has a variable number of bytes (up to 31) ♦ 
LFA 

following the name field, a two byte link field, which contains the HFA of the first word 

in the sane vocabulary which immediately precedes this one* 

CFA 

following the link field, a two byte code field which points to the word's execution code* 
PFA 

following the code field, a variable length parameter field* 

In Coin-Op FORTH, the link, field cones before the name field, with the code field coning 
immediately after the name field* The structure is thus* 
LFA NFA CFA PFA 

This improves the speed of dictionary searches, since the LFA of a word will have a fixed offset of 
-2 from the NFA rather than a variable offset* 

NOTE** in fig-FORTH, the last character in a nane field has its high bit set ($80)* Because only 
this character can have this bit set, nates cannot have ATASCII inverse characters in then. To wake 
sure that this is the case, all words in the input stream are operated on by the word 7BITS, which 
changes any inverse characters in a word to normal characters by setting the high bit to 0* Thus, to 
FORTH inverse arid normal ATASCII characters in a nane are identical* 

Linking and "Sub-vocabularies" 

Normal fig-FORTH has all words in a given vocabulary linked together } ths most recently defined 
word links directly (through its LFA) to the NFA of the word defined before that, which links to the 
word before that, and so on, down to the very first word in the vocabulary* (See Starting FORTH, 
PP ♦212-44, for a good discussion of vocabularies arid linking*) Coin-Op FORTH has Modified this 
system through the creation of "sub-vocabularies" within vocabularies* 

During compilation, each word in a vocabulary is placed in one of 8 sub-vocabularies* The 
number of sub-vocabularies is determined by the constant *LBKS, which is set to 8*) These 
sub-vocabularies nay be numbered fron 0 to 7. Hhich sub-vocabulary a word belongs in is deternined 
by the ATASCII value of the first character of that word's nane* That value is divided by 8, and the 
renainder (0-7) determines which sub-vocabulary the word will belong to* Thus, a word beginning with 
H (ATASCII value $48) will be placed in sub-vocabulary 0, as will a word beginning with X ($58), 8 
($38), or E ($40)* A word beginning with L ($4C), on the other hand, will be placed in 
sub-vocabulary 4* while a word beginning with N ($57) will be in sub-vocabulary 7, and so forth* 
Thus, the words in each vocabulary have been "hashed", according to their ATASCII value, into 8 
groups* 

The words in each sub-vocabulary are linked together in the nornal manner} the LFA of the most 
recently defined word in a sub-vocabulary points to the NFA of the word in the same sub-vocabulary 
defined just before that, arid so forth down to the first word defined in that sub-vocabulary ♦ Hords 
in one sub-vocabulary thus are linked only to each other, arid not to those in arry other 
sub-vocabulary* 

Now, look at what happens when a dictionary search occurs* As an example, assume that the word 
DUP has just been encountered in the input stream* The search routine takes the first letter (D) of 
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this word, and fro* it determines which sub-vocabulary the word nust be in, if its exists at all* 
(This task of "hashing" is performed, logically enough, by the word HASH*) In the case of DUP, 
sub-vocahulary *4 is duly searched, arid DDF' is found ♦ The point is that the other 7 sub-vocabularies 
need not be searched , and thus on average onl^ 1/8 as Many words will need to be looked at in any 
given dictionary search in Coin-Op FORTH, as opposed to in a FORTH which uses only one "link-chain"* 
This is the Main reason why Coin-Op FORTH compiles code so nuch faster than fig-FORTH* 



Vocabularies 

A knowledge of the structure and purpose of FORTH vocabulary definitions is necessary in order 
to under stand the following discussion* All About FORTH by Glen B* Haydon and FORTH Encyclopedia by 
Derick and Baker contain good discussions of vocabularies* It should be noted that new vocabularies 
need not chain directly to the FORTH vocabulary*, any vocabulary way serve as a "parent vocabulary". 
This in turn allows an ever-expanding branching structure of vocabularies within the dictionary* 
Eventually, of course, all vocabularies will chain at least indirectly to FORTH* 

The changes to the header structure and the addition of sub-vocahularies have necessitated two 
changes to the structure of vocabulary definitions in Coin-Op FORTH* 

h Instead of one vocabulary entry pointer (or, if you prefer, "Vocabulary link field") 
in each vocabulary definition, there are now eight, one for each sub-vocahulary* Since 
each entry pointer needs 4 bytes (two for the pseudo-nane field, two for the link), a 
total of 32 bytes is required* Sub-vocabulary *0 uses bytes 1 to 4 as its entry pointer, 
sub-vocahulary *2 uses bytes 5 to 8, and so forth* In this way, sub-vocabulary *n of a 
child vocabulary chains to sub-vocabulary #n of its parent* 

2^ The pseudo-NFA of each entry pointer now follows the LFA, rather than vice versa*, 
this is due to the change in header structure decribed in the above section on Headers* 

MUST 

MUST has been modified so that it will still print out the CONTEXT vocabulary words in the 
order in which they are placed in the dictionary* However, in vocabularies to which the CONTEXT 
vocabulary chains (unless the CONTEXT vocabulary is FORTH, of course) all of the words in 
sub-vocabulary *7 will be listed in order first, followed by those in sub-vocabulary 6, 5, and so on. 
(This is because MLIST sets up a table of the NFAs of the next word in each sub-vocabulary} the word 
in this table with the highest NFA is printed by MUST, arid its NFA is replaced with that of the word 
to which it links} this process then repeats for the next word, arid so on to the bottom of the 
dictionary* This works fine, until all of the NFAs in the table are the "pseudo NFAs" in the parent 
vocabulary? at this point, sub-vocabulary *7's NFA is the highest address in the table, as are the 
NFAs of all of the subsequent words in the parent vocabulary's sub-vocabulary *7* Thus, all words in 
sub-vocabulary M will be listed until it is exhausted, after which all words in sub-vocabulary *6 
will be listed, etc*) This will continue until the word FORTH is itself encountered, after which 
words will again be listed in order of their physical location in the dictionary as a whole* 

Disk Access and Disk Buffers 

Many users will never need to worry about Coin-Op FORTH' s primitive disk access and disk, buffer 
words*, the higher level words LIST, LOAD, BLOCK, arid BUFFER provide a great deal of flexibility and 
Coin-Op FORTH does use the standard fig-FORTH word R/W* Below the level of these words, however, 
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Coin-Op FORTH 's disk words are tailored to the Atari arid as such they differ fro* nornal fig-FORTH 
usage * The following discussion is intended for those who either need to know or are interested in 
knowing what these differences are* The one section which nay he of wore general interest is that on 
the numbering of disk blocks* 

Disk Access 

Coin-Op FORTH dos not use the standard fig-FORTH disk access words , BLOCK-READ and EL0CK4&TTE* 
Instead, CoirrOp FORTH utilizes words which directly call the Atari SIO routines* These words are 
SECIO and SID, which in turn are called by DIO (for single density disk drives) arid DDIO (for double 
density disk drives), basically, the procedure for disk, access is to set up a device control block 
(see the Atari OS Manual and the words ICAL, ICCM, ICLL) and execute SECIO* 

Screen Numbering 

1* Coin-Op FORTH allows for a difference between physical and logical screen numbering* This is 
accomplished by storing a value into the user variable FWSOFF (normally set to 12)* This value is 
added by the disk access words to whatever logical block., number is supplied by the user in order to 
obtain the physical block number* This allows the user to put the bootable object on a disk onto 
"negative" logical screens* Note that it is very difficult to use logical screen 0 on a disk to hold 
source code (see INTERPRET)* 

2* The logical screen supplied by the user is interpreted by Coin-Op FORTH as follows* 

Each block. * is 16 bits, of which the highest bit is not used* The low 11 bits ($0 - 
$7FF) indicate the screen number* The next two bits (12 arid 13) indicate the drive *, and 
the two bits above those (14 and 15) indicate the drive type* Consult the following chart 
to see what values to add to a given logical block number* 



Add this value 4 * To access drive ♦* 

$0000 1 

$0800 2 

$1000 3 

$1800 1 

Add this value: To access drive type! 

$0000 810-type 5 1/1" single density 

$2000 815 or 8" double density 

$4000 8" single density DEC interleave 

$6000 8" single density non-interleaved 



Disk Buffer Control 



Coin-Op FORTH uses a table called FT AD to control disk buffers* This table contains four 
"entries", each corresponding to a disk, block* The first entry contains information on the most 
recently accessed block, the second contains information on the next most recent block, and so forth* 
At the moment, only two disk buffers are used by Coin-Op FORTH, and as such only the first two 
entries of PTAB are used* The two buffers each consist of $400 (IK) bytes, and they begin at $500 
and $900, respectively* 

Each entry in the disk buffer table consists of 5 bytes* The first two bytes contain the 
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logical block, number* The second two bytes contain the starting address of the buffer in which the 
block is contained* The last byte indicates the status of the buffer (0 = not in use, 1 = in use, 81 
= updated)* 

When a new block, is accessed it is placed in the buffer which was least recently used* The 
block number, buffer address, and status of this block are placed in the first entry in the disk, 
buffer table, while the old contents of the first entry are placed in the second entry* (If a third 
buffer was in use, the contents of the third entry would indicate the least recently accessed block, 
and the contents of the second entry would be placed in the third entry when a new block, was 
accessed} likewise with a fourth buffer*) If the block in the least recently accessed buffer is 
Marked as updated, its contents are written to disk, before a new block is read into that buffer* 

The contents of the variable PREV point to the first byte of the ttost recently accessed buffer 
entry (entry *1) in PTAB* The contents of the variable ALT (which roughly corresponds to the 
fig-FORTH word USE) point to the entry for the least recently accessed buffer (entry *2)* FORTH and 
the user can thus access the disk buffer information via these words* (MOTE I a third disk buffer 
could be added by pointing ALT to the third entry in PTAB (PTAB +$A) and placing a buffer address 
into the third and fourth bytes of this entry* The sane technique could be used for a fourth disk 
buffer* DO HOT put the new buffer or buffers right above the old ones! FORTH starts at $D00* Put 
thett sonewhere above the dictionary* 
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n addr — 

Store 16 bit value r« at address* Pronounced "store" * 



Save the stack position in CSP* Used as part of 
dl — dZ 

Generate, fro* a double nutter dl, the next ATASCII character which is placed in an output 
string* Result d2 is the quotient after division by BASE and is Maintained for further 
processing* Used between <* and #>♦ See *S* 

d — addr count 

Terminates numeric output conversion by dropping d, leaving the text address arid character 
count suitable for TYPE* 

— n 

Constant leaving the number of link chains in each vocabulary* For a full explanation of 
the linking systeh (which is different from that of normal fig-FORTH), see the discussion 
of linking which precedes this glossary* 



dl — d2 

Convert all digits of double-number dl to their AT ASCII equivalents, adding each to the 
pictured numeric output text, until- the remainder is 0 (this remainder is left as d2)* A 
single 0 is added to the output string if the initial value of dl is 0* Used between <# 
and *>. 

— addr 
Used in the form** 
' rvm 

If executing, leaves the PFA of the next word accepted fro« the input stream* If 
compiling, compiles the PFA as a literal*, later execution will place this value on the 
stack.* If the word is not found after a search of CONTEXT and CURRENT, an appropriate 
error message is given* This is defined as an immediate word. Pronounced "tick"* 



Used in the form** 
( cccc) 

Accept arid ignore comment characters from the input stream, until the next right 
parenthesis* Since it is a FORTH word, ( Must be followed by at least one blank* It nay 
be used freely while executing or compiling* Contents nay not be longer than 255 
characters, arid an error condition exists if the input stream is exhausted before the 
right parenthesis* 

The run-time procedure compiled by +L00P, which increments the loop index by n and tests 
for loop completion* See +LOOP* 
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(.") 



The run-tirte procedure, compiled by #" which transnits the following tit-lite text to the 
selected output device* See 



(JCODE) 



(ABORT) 



(DO) 



The run-time procedure, compiled by *,C0DE, that rewrites the code field of the most 
recently defined word to point to the Machine code sequence which follows JCODE* See 
JCODE* 



Executes after an error when HARMING is -1J also executes after a RESET or BREAK* This 
word normally executes ABORT , but May be altered (with care) to execute a user's 
alternative procedure* 



The run-tine procedure compiled by DO which Moves the loop control paraMeters to the 
return stack* See DO* 



(FIND) addrl addr2 — pfa b tf (found) 

addri addr2 — ff (not found) 
Searches the dictionary starting at the NFA addr2, hatching to the text at addrl* Returns 
paraweter field address, length byte of the narte field and boolean true if a Match is 
found* If no Match is found, only a boolean false is left* 



(LINE) 



ni n2 — addr 32 

Converts the line nuhher nl arid the screen n2 to the starting address of that line in the 
disk buffer* If screen n2 is not already in memory, it is read from disk to buffer* The 
count of 32 indicates the length of a text line. 



(LOOP) 



The runrtiwe procedure coMpiled by LOOP, 
completion. See LOOP* 



Increments the loop index and tests for loop 



(NUMBER) 



dl addrl — d2 addr2 

Convert the AT ASCII text beginning at addr 1+1 with regard to BASE* The new value is 
accumulated into double number dl, being left as dZ. Addr 2 is the address of the first 
unconvertable digit* Used by NUMBER* 



nl n2 — n3 
Leave the arithmetic sum n3 of nl+n2. 



+ ! 



n addr — 

Add n to the 16-bit value at the address* Pronounced H 



ii 
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nl n2 — n3 
Negate nl if n2 is negative* 



nl — (run-tine) 
addr n2 — (conpil-tine) 
Used in 3 colon-definition in the fornt 
DO .♦* nl +LD0P 

At run-tine, +L00P selectively controls branching back to the corresponding DO based on 
nl t the loop index and the loop Haiti The signed increment nl is added to the index and 
the total is compared to the Unit* The branch back to DO occurs until the new index is 
equal to or greater than the Unit (nl>0), or until the new index is equal to or less than 
the linit (nl<0)* Upon exiting the loop, the parameters are discarded and execution 
continues beyond LOOP* 

At ccwpile tine, +LD0P compiles the run-tine word (+L00P) arid the branch offset computed 
trow VEPE to the address left on the stack by DO* n2 is used for compile tine error 
checking* 

n — addr 

Leave the nenory address which is n bytes above the "origin" ♦ n is given in terns of 
bytes* This definition is used to access or nodify the boot-up parameters at the origin 
area* The "origin" in Coin-Op FORTH is at *D00* 



Allots 2 bytes in the dictionary and stores n there* Pronounced! "coma"* 
nl n2 — n3 

Subtract nZ fron nl arid leave the difference as n3* ' 



Used on a disk screen* Causes the next disk screen to be loaded* Interpretation 
continues on this screen* (Pronounced "next-screen")* 



n — n (zero) 
n — n n (non-zero) 

Reproduce n only if it is non-zero* This is usually used to copy a value just before IF* 
to eliminate the need for an ELSE part to drop it* 

— pfa b tf (found) 

— ff (not found) . 

Accepts the next text word (delimited by blanks) in the input strean to HERE* and searches 
the CONTEXT and then CURRENT vocabularies for Matching entry* (Searches continue on into 
parent vocabularies} the CURRENT vocabulary is searched only if it is not the sane as the 
CONTEXT vocabulary)* If found, the dictionary entry's paraneter field address* its length 
byte, and a boolean true is left* Otherwise, only a boolean false is left* 
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-TRAILING 3ddr nl — addr rtZ 

Adjusts the character count nl of a text string beginning at addr to suppress the output 
of trailing blanks* i*e* the characters at addr+nl to addr+nZ are blanks* Read "not 
trailing"* 

i nl nZ — n3 

Leaves the signed arithmetic product of two signed numbers* 



1/ nl nZ n3 — vA 

Leaves the ratio rrt = nl*nZ/n3 where all are signed numbers* Retention of an intermediate 
31 bit product permits greater accuracy than would be available with the sequence** 
nl nZ x n3 / 



ti 

4 





nl nZ n3 — ifi n5 

Leaves the quotient n5 arid remainder rrt of the operation nl*nZ/n3* A 31 bit intermediate 
product is used (as for 

Display n f converted to AT ASCII according to BASE t in a fixed-field format* Prints the 
sign only if n is negative* A trailing blank follows* Pronounced ,, dot ,, « 



Used in the form** 



*" cccc" 



Accepts the following text from the input stream, delimited by " (double-quote)* If 
executing, the text is transmitted to the output device* If compiling, compiles the text 
(with the count in the first byte) along with the execution procedure (♦") so that later 
execution will transmit the text to the output device* The text may be up to 255 
characters long* 



♦LINE nl n2 — 

Print line nl of disk screen n2 on the terminal device* Trailing blanks are suppressed* 

All AT ASCII control characters are printed* 



*R nl nZ — 

Prints the number nl right aligned in a field of width n2* No following blank is printed* 
If nZ < If no leading blanks are supplied* 

/ nl n2 — n3 

Divides nl by nZ and leaves the signed quotient n3 (which is rounded toward 0)* 



nl ri2 — n3 rrf 

Divides nl by n2 arid leaves the remainder n3 arid quotient tA* The remainder n3 has the 
same sign as the dividend nZ* 
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These snail numbers are used so often that it is attractive to define then by name in the 
dictionary as constants, because constants take less dictionary space arid less dictionary 
search tine than do numbers ♦ 

n — f 

Leaves a true flag if n is less than zero (negative), otherwise leaves a false flag* 



n — f 

Leaves a true flag if n is equal to zero, otherwise leaves a false flag* 

The run-time procedure to conditionally branch* If f is false (zero), the in-line 
parameter which follows it is 36^6 to the interpretive pointer to branch ahead or back.* 
Compiled by IF, UNTIL, arid WHILE* 

n — ri+1 
Increments n by 1* 

n — n+2 
Increment n by 2* 



addr n — 

Sets the high bit of each byte of the n bytes starting with addr to 0* This converts any 
characters which are in inverse representation to their normal representations} FORTH 
treats inverse characters which occur in word names as if they were normal characters* 



Used in the form** 

t cccc ♦♦♦ *, 

Creates a dictionary header for cccc in the CURRENT vocabulary, sets CONTEXT equal to 
CURRENT, arid sets compile mode* Also, sets the CFA of cccc to point to run-tine code 
which follows i in the dictionary* The compilaton addresses, CFA, of subsequent words in 
the input stream which are not immediate will be compiled into the dictonary by INTERPRET t 
to be executed when cccc is later executed* (Immediate words, i*e* those with their 
precedence bit set, will be executed when they are encountered.) Compilation of CFAs will 
continue until I is encountered. 

If a word which is part of a colon definition is not found after a search of both 
the CONTEXT and CURRENT vocabularies, an error conditon exists. 

Terminates a colon-definition and stops further compilaton. Compiles the run-time routine 
*,S. If compiling from mass storage arid the input stream is exhausted before } is 
encountered, the machine may crash. 
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Used in the form J 

S ccc . ♦♦♦ JCCDE assembly mnemonics 
Stops compilation arid terminates a new defining word cccc by compiling (*,C(X>E)* Sets the 
CONTEXT vocabulary to ASSEMBLER , assembling to machine code the mnemonics which follow it* 



When cccc later exeDjtes in the formi 
cccc nrmn 

the word nnrm will be created, and its execution address will contain the address of the 
machine code following JCODE in cccc* That is, when nrmn is executed, it does so by 
jumping to the code after mm*- 



Stops interpretation of a screen. }S is also the rurrtime word compiled at the end of 
colon-definition which returns execution to the calling procedure* 

nl ri2 f 

Leaves a true flag if nl is less than n2{ otherwise leaves a false flag* 




•(BUILDS 



Initializes pictured numeric output, which uses the words*" 
<* * *S SIGN !> 

The conversion to ATASC3I is done on a double number and produces text at PAD* 



<BWLDS is used in conjunction with DOES) to created defining words* Used in the form! 
J cccc <BUILDS ♦♦♦ 
D0ES> *** 

Hhen cccc is later executed in the form cccc bbbb, <BUILDS creates a dictionary entry for 
the new word bbbb* First, a header for bbbb is created* Then the sequence of words 
between <BU3LDS and D0ES> establishes a parameter field for bbbb* Hhen bbbb is later 
executed, its PFA will be placed on the stack and the sequence of words following D0ES> in 
cccc will be executed* 



nl n2 — f 

Leaves 3 true flag if nl=ri2 i otherwise leaves a false flag. 



Leaves a true flag if nl is greater than n2J otherwise leaves a false flag. 



>R 



n 



Removes the top value from the stack and places it on the return stack* 
balanced with R> in the same nesting level of a colon definition* 



Use of >R must be 



?C0MP 



addr — 

Prints the contents of memory location addr in free-format according to the current base* 



error message if rot compiling* 
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?CSP 



error Message if stack position differs fro* value saved in CSP. 



Ill ■ ■ ■ Mto^ 

TERROR 



f n — 

Issues an error Message nunber ft, if the boolean flag is true. 



7EXEC 



Issues an error Message if not executing* 



7LDADING 



?PAHB 



7STACK 



Issues an error Message if not loading* 



Issues an error Message if nl does not equal n2* The Message indicates that cottpiled 
conditionals do not Match* 



Issues an error Message if the stack is out of bounds % 




7TERMINAL 



PerforMS a test of the terMinal Keyboard to see if the break key has been pressed. A true 
flag indicates the key has been pressed* (In Coin-Op FORTH* this routine always returns a 
false flag? testing for BREAK occurs during TYPE and KEY*) 



addr — n 

Leaves the 16 bit contents of addr on the stack* Pronounced "fetch" 



Clears the data and return stacks and enters execution Mode* Returns control to the 
operators terMinal* printing a Message appropriate to the installation* Execution of the 
abort routine is vectored through ABORT to (ABORT) J the actions of ABORT can thus be 
changed as the user desires (as long as (ABORT) is involved as the final part of the 
changed routine)* 



AES 



nl — n2 

Leaves the absolute value of a nunber* 



AGAIN 




— (execution) 

addr n — (coMpiling) 
Used in a colon-definitiion in the for-M* 
BEGIN ♦♦♦ AGAIN 

At rurrtiwe, AGAIN forces execution to Jump unconditionally to the corresponding BEGIN* 
There is no effect on the stack* Execution cannot leave this loop (unless R> DROP is 
executed one level below)* At coMpile tine, AGAIN coMpiles BRANCH with an offset fro* 
HERE to addr* n is used for coMpile-tiMe error checking* 
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Adds n bytes In nay be positive, negative, or zero) to the parameter field of the nost 
recently defined word* Updates DP by n bytes ♦ Hay be used to reserve or delete 
dictionary space* 



— addr 

A variable which contains the address of the entry in the disk buffer control table which 
corresponds to the disk buffer least recently referenced (this buffer will be used to hold 
the next source screen)* 



nl n2 — r»3 

Leaves the bitwise logical "and" of nl and n2 as n3. 

This constant leaves the nuwber of bytes per disk block buffer* This is 1023 (IK) in 
CoirrOp FORTH* 



This constant leaves the nunber of blocks per editing screen* Conventionally* an editing 
screen is 1023 bytes organized as 16 lines of 63 characters each* However, in Coin-Op 
FORTH, an editing screen is 1023 bytes organized as 32 lines of 32 characters each, due to 
the width of the Atari display screen* 

addr — 

Calculate the backward branch offset fron HERE to addr and conpile this offset into the 
next available dictionary nenory address* 

— addr 

A user variable containing the current nunber base used for numeric input and output 
conversion. 

BEGIN — addr n (compiling) 

Occurs in a colon-definition in fornt 
BEGIN *** UNTIL 
BEGIN .** AGAIN 
BEGIN ♦*♦ WHILE *.♦ REPEAT 
At run-tine* BEGIN harks the start of a sequence that nay be repetitively executed* It 
serves as a return point fron the corresponding UNTIL, AGAIN or REPEAT. When executing 
. UNTIL, a return to BEGIN will occur if the top of the stack is false} for AGAIN and REPEAT 
a return to BEGIN always occurs. 

At conpile tine BEGIN leaves the return address for UNTIL, AGAIN, or WHILE and n for 
conpiler error checking on the stack. 





TT *> 
J — L ♦ j— 




BFHD 



n — addr (found) 

n — f (riot found) 

Checks to see if block n is already contained in a disk buffer which is Marked as "in 
use". If it is, returns addr, which is the address of that buffer's entry in the disk 
buffer control table (PTAB)* If not, returns a 



BL 



A constant that leaves the ascii value for "blank" ♦ 



BLANKS 



addr n 

Fills an area of memory beginning at addr with an ATASCII (value = 20) ♦ 



BLK 



— addr 

A User variable containing as the input stream the block, number being interpreted* If 
zero, input is being taken from the terminal input buffer* 



BLOCK 




EfiANCH 



n — 

Leaves the memory address of the block buffer containg block. n« If the block is not 
already in memory arid marked as being "in use", it is transferred from disk to whichever 
buffer was least recently written, and that disk buffer is established as the "current" 
buffer* If the block occupying that buffer has been harked as updated, it is rewritten to 
disk before block n is read into the buffer* See also BUFFER, R/H UPDATE aiJSH* 



The run-time procedure to unconditionally branch* An in-line offset is added to the 
interpretive pointer IP to branch ahead or back. BRANCH is compiled by ELSE, AGAIN, 
REPEAT * An in-line branch offset must follow any compiled instance of the ideogram* 



BUFFER 



C! 



n — addr 

Obtains the next memory buffer (indicated by ALT)* 
is written to the disk*, the buffer is then 
first cell within the buffer for data storage* 

n addr — 

Stores the least significant 8 bits of n at addr* 



If the buffer is marked as updated, it 
block n* The address left is the 



n 



Constant leaving the number 
32* 



of characters per FORTH screen line. For the Atari, this is 



C 




Stores the lower order byte of n into the next available dictionary byte, advancing the 
dictionary pointer. 
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a? 



3ddr — b 

Leaves on the stack the contents of the byte* (The value on the stack will be 16-bit with 
the high byte set to zero)* 



CFA 



pfa — cfa 

Converts the parameter field address of a definition to its code field address* 



CMOVE 



addrl, addr2, n — 

h bytes beginning at address addrl to address addr 2* The contents of address addrl 
is moved first* proceeding toward high memory* If n is 0* nothing is moved* n must be 
greater than or equal to 0 for this ideogram to function properly* 



COLD 



The cold start procedure to adjust the dictionary pointer to the minimum standard arid 
restart via ABORT* Hay be called from the terminal to remove application programs and 
restart* Cold start 
"origin" ($D00) in memory* 



COMPILE 



CONSTANT 



Nhen a word containing COMPILE executes, the 10-bit value following the compilation 

address of COMPILE is copied (compiled) into the next available position in the dictonary* 

i*e*, COMPILE DUP will' copy the CFA of DIP* COMPILE is usually used within immediate 
words such as IF arid DOES>. 



n 



A defining word used in the form** 
n CONSTANT cccc 

to create a dictonary entry for cccc, with its parameter field containing n* When cccc is 
later executed, n will be placed on the stack* 



CONTEXT — addr 

A user variable containing a pointer to the vocabulary within which dictionary searches 
will begin during interpretation of the input stream* 



COUNT 



addr — addr+l n 

Leaves the address and the character count n of the text beginning at addr* It is 
presumed that the first byte at addr contains the text byte count arid the actual text 
starts with the second byte* n ranges from 0 to 255* Typically COUNT is followed by 
TYPE* 



CR 



Causes a carriage return arid line feed to occur on selected output device* 
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CREATE 



CSP 



A defining word used in the form** 
CREATE cccc 

by such words as CODE and CONSTANT to create a smudged dictonary header for a FORTH 
definition* The code field of the new word contains the address of the word's parameter 
field. The new word is created in the CURRENT vocabulary* 



addr 

A user variable which can be used to store temporarily the stack pointer position, for 
compilation error checking* 



CURRENT — addr 

A user variable which specifies to which vocabulary new word def initions will be added* 
In dictionary searches, the CURRENT vocabulary is searched second, after the CONTEXT 
vocabulary* 



dl d2 — d3 

Leaves the double number sum d3 of two double numbers dl arid d2* 



D+- 



dl n — d2 

Negates the double number dl if n is negative* 




Di 



Prints the double number d, converted to ATASCII according to BASE, in a free field 
„ with one trailing blank* Displays the sign only if negative* 



d n — 

Prints a signed double number d, converted to ATASCII according to BASE, right-aligned in 

a field n characters wide* Displays the sign only if negative* If n=0, does not 
right-align the value* 



D8U* 



dl, n — d2 

Multiplies an unsigned double number dl by the unsigned 8-bit value n, leaving the product 
as an unsigned double number d2* 



DAES 



dl — d2 

Leaves the absolute value of a double number* 



DDIO 




n 



Reads or writes 256 byte sector n on a double density disk* The read or write must be set 
previous to entry to DDIO by setting the command byte of the device control block* The 
buffer address for reading or writing must also by preset*, this address is incremented by 
256 at the end of DDIO to prepare for reading or writing the next sequential sector* 
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DECIMAL 



Sets the numeric conversion base for input-output to ten* 



DECHAP 



nl ri2 - nl n3 

Gives the logical sector number n2, returning the proper physical sector number n3 for use 
with a single density 8" disk drive* nl=0 indicates a non-interleaved drive} nl=8000 
irrdicates a DEC interleave drive* 



DEFINITIONS 



Sets CURRENT to the CONTEXT vocabulary* so that subsequent definitions will be added to 
the vocabulary previously selected as CONTEXT* (Often used in the form** 

cccc DEFINITIONS 
where cccc is a vocabulary name)* 



DIGIT 



c nl — n2 tf (valid conversion) 

c nl ff (invalid conversion) 

Converts the ASCII character c (using base nl) to its binary equivalent n2, accompanied by 
a true flag* If the conversion is invalid, leaves only a false flag* 



DIO 




n 



Reads or writes 128 byte sector n on a single density disk* The read or write Must be set 
previous to entry to DIO by setting the command byte of the DCB* The buffer address for 
reading or writing must also be preset; this address is incremented by 128 at the end of 
DIO to prepare for reading or writing the next sequential disk sector* 



DUTERAL 



d — d (executing) 
d — (compiling) 

If compiling, compiles a stack double number into a literal along with a run-time routine 
(LTD* Later execution of the definition containing the literal will push it onto the 
stack* If executing, the number will remain on 



DMINUS 



dl — d2 

Converts dl to its double number two's complement. 
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D0ES> 



DO nl n2 — (execute) 

addr n (compile) 

Occurs in a colorr-def initiori in form** 
DO LOOP 
DO ♦♦♦ +L00P 

At ruri tif^e t DO begins a sequence with repetitive execution controlled by 3 loop limit nl 
and an index with initial value n2« DO removes these from the stack. Upon reaching LCK3P 
the index is incremented by one. If +L00P is used, the index is incremented by the value 
on top of the stack* This value may be negative, i*e*, the loop nay run with its index 
decreasing to a lower limit*, see +L00P) Until the new index equals or exceeds the limit, 
execution loops back to just after DO*, when the index does equal or exceed the limit the 
loop parameters are discarded and execution continues beyond loop* Both nl and n2 are 
determined at run-time and may be the result of other operations* Both nl and n2 are 
signed 16-bit values* Within a locp 'I' will copy the current value of the index to the 
stack-.* See I, LOOP, +L00P, LEAVE* When compiling within the colon-definition, DP 
compiles the run-time code (DO), leaves the following address addr arid n for later error 
checking ♦ 



in conjunction with <BUILDS to create defining words* Used in the form! 
*♦ cccc -(BUILDS ***D0ES> ♦♦♦ *, 
It marks the terminator* of defining code arid the start of run-time code in cccc* 

When cccc is executed in the form cccc hhhb, D0ES> alters the code field address and the 
first parameter of bbbb so that, when bbbb is executed, the sequence of words following 
DOES)- in cccc will be executed* (The PFA of bbbb will be on the stack when this exearlion 
begins, allowing the parameters of bbbb to be used by the code following DOES)* 



Ur addr 

A constant which returns the address (or 0 page) of the dictionary pointer, which contains 
the address of the next free memory above the dictionary* The value may be read by HERE 
arid altered by ALLOT* 



DPL addr 

A user variable containing the number of digits to the right of the decimal on double 
integer input* It may also be used to hold output column location of a decimal point, in 
user generated formating* The default value on single number input is -1* 



DRO — 
DR1 

Commands which select disk drives, by presetting OFFSET* DRO selects "drive 1"* DR1 
should select "drive 2"} however, it actually selects "drive 3"* The contents of OFFSET 
is added to the block number in EtOCK to allow for this selection* Offset is supressed 
for error text so that it may always originate from the first drive* 

DROP n — 

Drops the top number from the stack* 
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DUP n — n n 

Duplicates the top value on the stack* 

I 0 

ELSE addr nl — addr 2 n2 

(compiling) 

Occurs within a colon-definition in the formt 
IF ♦ *. ELSE *♦* ENDIF 

At run-tine, ELSE executes after the true part following IF* ELSE forces execution to 
skip over the following false part arid resumes execution after the ENDIF* It has no stack 
effect* 

At compile-time ELSE compiles BRANCH and reserves space at addr2 for a branch offset which 
will be resolved by ENDIF} it then leaves the address addr2 and n2 for error testing* 
ELSE also resolves the pending forward branch from IF by calculating the offset from addrl 
to HERE arid storing it at addrl* 



EMIT 



Transmits AT ASCII character c to the selected output device* 



EMPTY-BUFFERS — 

Marks all block-buffers as empty, without affecting the contents* Updated blocks are not 
written to the disc* This is also an initialization procedure before first use of the 



ENCLOSE addrl c — 

addrl nl n2 n3 

The text seaming primitive used by WOFD* From the text address addrl and an ATASCIE 

delimiting character c* the following offsets are determined 4 * 

nl is the offset from addrl to the first non-delimiter character 
n2 is the offset from addrl to the first delimiter c after the text 
n3 is the offset from addrl to the first character beyond addrl+n2 



END 



This is a synonym for UNTIL* 



addr n — (compile) 
Occurs in a colon-def inition in formt 
IF *♦. ENDIF 
IF .** ELSE ♦** ENDIF 

At run-time* Dfl)IF serves only as the destination of a forward branch from IF or ELSE* It 
marks the conclusion of the conditional structure* TI€N is another name for ENDIF* tath 
names are supported in fig-FORTH* See also IF and ELSE* 

At compile-time, ENDIF computes the forward branch offset from addr to HERE and stores it 
at adr* n is used for error tests* 
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ERASE addr r» — 

Sets n bytes, starting from addrl to 0* 

ERROR line — in blk 

Executes error notification arid restart of system* HARKING is first examined* If 1, the 
text of line n, relative to lire 0 of screen 4 on drive 0 is printed* This line nuhber 
way be positive or negative, arid hay lie beyorid screen 4* If HARNBIG=0, n is just printed 
as a message number* If HARKING is -1, the definition (ABORT) is executed, which executes 
the system AEtIRT* The user hay cautiously Modify this execution by altering (AKH\T)* 
Fig-FORTH saves the contents of IN and BLK to assist in determining the location of the 
error* Final action is execution of QUIT* 

EXECUTE cf a — 

Executes the definition whose code field address is on the stack* Different frow starting 
FORTH, which takes pfa* 

EXPECT addr n — 

Transfers characters from the terminal to address, until a "return" or the count of n 
characters has been received* Takes no action for n less than or equal to 0* One or more 
nulls are added at the end of the text* 

FENCE — addr 

A user variable containing an address below which FORGETting is not allowed* To forget 
below this point the user Must alter the contents of FENCE* 

FILL addr n b — 

Fills Memory starting at addr with a sequence of n copies of byte b* n>0* 

FIRST — n 

A constant that leaves the address of the first (lowest) block buffer* 

FID — addr 

A user variable for control of number output field width* Although defined, this ideogram 
is not currently used by fig-F(FTH implementations* 



FLUSH — 

Hrites all blocks which have been flagged as updated to display arid mark them as "in use" 
rather than "updated"* 
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Executed in the forn*" 
FORGET cccc 

Deletes word cccc froh the dictionary along wih all words added to the dictionary after 
cccc, regardless of their vocabulary ♦ If cccc cannot be found in a search of the CONTEXT 
and CURRENT vocabularies, or if cccc's definition lies below the address contained in 
FENCE, an error message will be delivered* In addition an error message will ocd.it if the 
CURRENT and CONTEXT vocabularis are not currently the sane* 



The mm of the prinary vocabulary* Execution hakes FORTH the CONTEXT vocabulary* All 
new definitions are added to the FORTH vocabulary until new vocabularies are created arid 
established as the CURRENT vocabulary* Vocabularies conclude by "chaining" to FORTH, so 
it should be considered that FORTH is "contained" within each of its descendant 
vocabularies* 

vl, addr, — v2 

Given addr, the starting address of a mm string in nettory, arid vl the address of the 
first sub-vocabulary entry pointer in a given vocabulary definition, returns v2, the 
address of the sub-vocabulary entry pointer in that vocabulary which points to the proper 
sub-vocabulary in which to search for an entry which hatches the nane string* In Coin-Op 
FORTH, each vocabulary has been hashed into 8 sub-vocabularies dependent on the AT ASCII 
value of the first character of a word's nane« 

See VOCABULARY and the user Manual description of Coin-Op FORTH linking* 
— addr 

Returns the address of the next available dictionary location* 



Sets the rower ic conversion base to sixteen (hexadecimal)* 



— addr 

A constant which returns the address of OS register HIMEN* This register contains the 
address of the last byte before the Atari display list (hence, the last byte usable by the 
dictionary)* 

— addr 

A user variable that holds the address of the latest character of text during numeric 
output conversion* 

c — 

Used between <* and t> to insert an ATASCII character into a pictured numeric output 
string* e*g* 2E HOLD will place a decimal point. (Output generation occurs frow high 
fiewory to low nenory.) 

— n 

Used within a DO-LOOP to copy the loop index to the stack* Alias for R* 




ELL 
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ICAL — addr 

A constant which returns the address of the buffer address entry in TXB \ 0 (used by 
keyboard and screen editor)* 



ICCM — addr 

A constant which returns the address of the connand byte in 1KB *0 (IOCB used by the 
keyboard and screen editor ) ♦ 



A constant which returns the address of the buffer length entry in IOCB *0 (IOCB used by 
the keyboard and screen editor)* 



3D NFA — 

Prints a definition's nane fron its nane field address* 



IF f — (run-tine) 

— addr n (compile) 
Occurs in a colon-definition in the forni 

IF (tp) ♦♦♦ ENDIF 

IF (tp) ♦♦♦ ELSE (fp) •.♦ENDIF 
At run-tine. IF elects execution based on a Boolean flag* If f is true (non-zero) ♦ 
execution continues ahead thru the true part* If f is false (zero), execution skips till 
just after ELSE to execute the false part* After either part* execution resunes after 
ENDIF i ELSE arid its false part are optional} if Kissing, false execution skips to just 
after ENDIF* 

At conpile-tine IF compiles OBRANCH and reserves space for an offset at addr* addr and n 
are used later for resolution of the offset and error testing* 



IMMEDIATE 



Mark the nost recently nade definition as a word which will be executed when encountered 
during compilation rather than conpiled (i*e* the precedence bit in its header is set)* 
The user nay force conpilation of an innediate definition by preceeding it with (COMPILE)* 



IN — addr 

A user variable containing the byte offset within the current input text buffer (terninal 
or disk) fron which the next text will be accepted. HORD uses and noves the value of IN* 



nl n2 — 

Prints the first line of each screen over the range nl, n2* This is used to view the 
initial connent lines of an area of text on disk screens* 




INPT — addr 

A user variable which serves as the keyboard input buffer in Coin-Op FORTH* 



2 Coin-Op FORTH 



P ♦ 



INTERPRET 



The outer text interpreter which sequentially executes or compiles text from the input 
stream (terminal or disk) depending on STATE ♦ If a word name in the input stream cannot 
be found after a search of CONTEXT and then CURRENT it is converted to a nwrtber according 
to the current base* That also failing, art error message echoing the name with a "?" will 
be given • Text input will be taken according to the convention for WORD* If a decimal 
point is found as part of a number, a double number value will be left* The decimal point 
has no other purpose than to force this action* See NUMBER* 



Returns the current index of the next outer loop* Hay be used only within a nested 
DO-LOOP structure* 



KEY 



LATEST 



Leaves the AT ASCII value of the next terminal key struck* If the key was an EOL (RETURN), 
a 0 is left on the stack, rather than $?B* ABORTs if the BREAK key is pressed* 

— addr 

Leaves the name field address of the most recently defined word in the CURRENT vocabulary* 



Forces termination of a DQ-LOOP at the next LOOP or +LQQP by setting the loop limit equal 
to the current value of the index* The index itself remains unchanged, and execution 
proceeds normally until LOOP or +L00P is encountered* 



pfa — lfa 

Converts the parameter field address of a dictionary definition to its link field address* 



LIMIT 



LIST 



n 



A constant leaving the address just above the highest memory available for a disk buffer* 
In CoirrOp FORTH, this is the beginning of the FORTH kernel (unlike other FORTHs, where 
the disk buffers are high up in RAM)* 



n 



Displays the ATASCII text of screen n on the selected output device* SCR contains the 
screen number during and after this process* 



LIT 



— n 



Within a colon definition, LIT is automatically compiled before each 16 bit literal number- 
encountered in input text* Later execution of LIT causes the contents of the next 
dictonary address to be pushed to the stack* 
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LITERAL n — n (executing) 

n — (compiling) 

■ 

If compiling, then compile the stack value n as a 16 bit literal* This definition is 
immediate so that it will execute during a colon definition. The intended use isi 

J xxxx [calculate! LITERAL } 
Compilation is suspended for the compile tihe calculatiori of a value. Compilation is 
resumed arid a LITERAL compiles this value along with the rurrtime code LIT* If not 
compiling, nothing happens arid n remains on the stack. 



LOAD r. — 

Read screen n from disk arid begin interpretation of it. If the word — > is encountered, 
screen n+1 will be loaded arid interpretation will continue on it* If either the word *,S 
or the end of a screen is encountered, interpretation will return either to the disk 
screen on which LOAD was encountered (i*e*» LOAD can be nested) or to the terminal. 



LOOP addr h — (compiling) 

Occurs in a colon-definition in form! 
DO ♦.. LOOP 

At rurrtime, LOOP selectively controls branching back to the corresponding DO based on the 
loop index and limit. The loop index is incremented by one arid compared to the limit* A 
branch back to DO occurs until the index equals or exceeds the limit*, at that time, the 
parameters are discarded and execution continues beyond LOOP. 

At compile-time, LOOP' compiles the rurrtime word (LOOP) arid uses addr to calculate an 
offset to DO* n is used for error testing* 

Hx nl n2 — d 

■ 

A mixed magnitude math operation which leaves the double number signed product of two 
signed numbers* 

d nl — n2 n3 

A mixed magnitude math operator which leaves the signed remainder n2 arid signed quotient 
n3, from a double number dividend d and divisor nl* The remainder takes its sign from the 
dividend* 



H/ttOD udl u2 — u3 ucH 

An unsigned mixed magnitude math operation which leaves a double quotient ucH and 
remainder u3, from a double dividend udl and a single divisor u2* 



HAX nl n2 — max 

Leaves the greater of two numbers* 



II *Z Coin-Op FORTH Kernel, Glossary, P* 20 




MESSAGE n — 

Prints on the selected output device the text of line n relative to screen 4 of drive 0* 
n may be positive or negative ■ MESSAGE nay be used to print incidental text such as 
report headers* If WARNING is zero, the message will simply be printed as a number. (If 
r. indicates a screen beyond screen 7 (ri>127), the text will actually be taken from line 
n-256. Thus, when n=128, text will be taken fro* screen 2, line 0 instead of 
line 0.) 



KB) rd n2 — nin 

Leaves the lesser of two rubers* 



MINUS td — n2 

Leaves the twos complement of a number ♦( Negates the number). 





MOO nl n2 — 

Divides nl by nZ t leaving the remainder n3 (with the sane sign as n2) . 

* 

NFA Pf a — nfa 

Converts the paraneter field address of a definition to its nacie field address. 

NUMBER addr — d 

Converts a character string left at addr (with the count in the first byte) to a 
double nuHberi using the current numeric base* If a decimal point is encountered in the 
text, its position will be given in DPI, but no other effect occurs* If numeric 
conversion is not possible, an error message will be given* The string must end with a 
blank,* 

OFFSET — addr 

A user variable which hay contain a block offset to disk drives* The contents of OFFSET 
is added to the stack, number by BLOCK. Messages printed by MESSAGE are independent of 
OFFSET* See BLOCK, DRO, DR1, MESSAGE. 



OR nl n2 — r»3 

Leaves the bit-wise inclusive "or" (n3) of two 16 bit values (nl,n2). 



OUT — addr 

A constant which returns the address of the OS register COLCRS. This register contains 
the horizontal position on the screen at which the next character will be put. The user 
may alter and examine OUT to control display for hatting. OUT is incremented by EMIT. 

OVER nl n2 — nl n2 nl 

Copies the second stack, value, nl, placing it as the new top. 

— addr 

Leaves the address of the text output buffer, which is a fixed number of bytes above HERE< 
This buffer is used as a "scratch pad" to hold characters for intermediate processing. 
Its capacity is 



* p ♦ 



1 




PFA 



nfa — pfa 

Converts the name field address of a compiled definition to its parameter field address . 



PHYSOFF — addr 

A user variable containing the value added to the logical block * to obtain the physical 
block * of a FORTH screen* This allows for "negative screens"* Used by various disk- 
access words* 



PREV 



— addr 

A variable containing the address of the entry in the disk, buffer control table (PTAB) 
corresponding to the disk buffer most recently referenced. The IPDATE command narks this 
buffer to be later written to disk* 



PTAEi 




QIERY 



— addr 

A variable whose parameter field contains the disk buffer control table* There are 4 
entries in this table* each containing five bytes* The first entry contains information 
on the disk, buffer containing the screen most recently accessed, while the second entry 
contains information on the buffer containing the screen which was accessed before that* 
The third or fourth entries are currently unused, as there are only two disk buffers} they 
could be used if more than 2 disk buffers were desired* The first cell of each entry 
contains the number of the screen contained in the block) the second cell contains the 
starting address of the buffer*, the last byte contains the status of the buffer (0 = not 
in use, 1 = in use, $81 = in use arid updated)* 



Accepts input of up to 120 characters of tad (or until a "return") from the operator's 
terminal* Text is placed in the terminal input buffer, whose starting address is 

IN is set to 0* 



QUIT 



Clears the return stack, stops compilation, and returns control to the operator's 
terminal* No message is given* This is the outermost word in FORTH*, it contains a loop 
which continually waits for input and then invokes INTERFIO* 



R 



n 



Copies the top of the return stack to the computation stack* 



R* 



— addr 

A user variable which may contain the location of an editing cursor, or other file related 
function* 



addr blk f — 

The fig-FORTH standard disk read-write linkage* addr specifies the source or destination 
block buffer, blk is the sequential number of the referenced block, and f is a flag where 
f=0 write and f=l read* R/W determines the location on mass storage, performs the 
read-write and performs any error checking* The type of disk drive arid the drive * are 
also indicated by blk} see the user manual for proper values* 
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— addr 

A user variable containing the initial location of the return stack* This ideogram is not 
actually defined in Coin-Op FORTH* However, the proper value has been stored in the user 
area at UP + 8 (see UP in the assembler glossary) arid the user can access it if necessary* 



Removes the top value from the return stack and leaves it on the computation stack* See 
/R and R* 



addrl nl addr2 n2 — (compiling) 
Used within a colon-def inition in the form** 

BEGIN ♦*♦ HHILE *** REPEAT 
At run-time, REPEAT forces an unconditional branch back to just after the corresponding 
BEGIN* 

At compile-time, REF'EAT compiles BRANCH and the offset fro* HERE to addrl* It then 
compiles the forward branch offset from addr2 to HERE and stores it at addr2 (resolving 
WHILE)* nl and n2 are used for error testing* 

nl n2 n3 — n2 r»3 nl 
Rotates the top three values on the stack, bringing the deepest to the top* 



Initializes the return stack pointer from user variable RO* (RO is not directly 
accessible to the user)* 

n — d 

Extend a signed single number to form a signed double number. 
— addr 

A user variable which contains the initial value of the stack pointer* This ideogram is 
not actually defined in Coin-Op FORTH and as such is not directly accessible to the user* 
However, the proper value has been stored in the user area at UP + 6 (see UP in the 
assembler glossary) arid the user can access it if necessary* It is useful for judging the 
depth of the stack and for setting up non-destructive stack dumps* 
Pronounced S-zero* See SP!* 



— addr 

A user variable containing the screen number most recently listed* This is used by 
various screen editing functions* 



n — 

Sets up the device control block to indicate a disk I/O operation should be performed on 
disk sector n, arid then executes SIO* If SIO returns an I/O error condition* an error 
message is sent to the terminal and ABORT is executed* Expects the command byte, buffer 
address arid length, and device ID * to be already set in the device control block* 
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SIGN 



n d — d 

Stores an AT ASCII sign just before 3 converted numeric output string in the tort 
output buffer When n is negative* n is discarded, bid double nunber d is maintained* 
Host be used between <* and #> (just before *)• 



SIO 



0 — - n 

Executes the Atari SIO (serial input/output) routine* Assumes that the device control 
block is properly set up* SIO is used for disk access* It returns n, where n=0 indicates 
no error occurred dur ing SIO, and n>0 indicates that an error * n+1 occurred during SIO* 



SHUDGE 



Used during word definition to toggle the "swudge bit" in a definition's name field* 
Setting this bit prevents an uncompleted definition from being found during dictionary 
searches, until compiling is completed without error* Orice the bit is set to zero, the 
definition can be found in searches* (NOTE! This allows the possibility of recursive 
definitions*) 



SP! 




SPACES 



Initializes the stack pointer fro* SO* (SO is not directly accessible to the user. See 



SO*) 



— addr 

Returns the address of the top of the stack, as it was just before SPB was executed. 



Transmits an ATASCIE blank to the output device* 



n 



Transmits n ATASCII blanks to the output device* Takes no action if n=0* 



STATE 



aoor 

A user variable containing the compilation state* A non-zero value indicates compilation, 
while a value of 0 indicates execution* 



SWAP 



TASK 



nl r*Z — ri2 nl 
Exchanges the top two stack values* 



A no-operation word which narks the boundary between the Coin-Op FORTH boot and 
applications* 
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— b f 
n — n b f 

Executes a call to CIO (the Atari central Input/Output routine) using IOCB * 0. Asswes 
that IOCB * 0 has been properly set up for whatever operation is desired* If the buffer 
length cell in IOCB is set to 0 on a "put" operaton, the top value on the stack, will be 
sent to the device (through the accumulator) but it will not be removed from the stack. 
The routine returns the value $80 if a break was encountered during the CIO routine} 
otherwise it returns a 0, Do not use interactively* 



THEN 



An alias for ENDIF* 



TIB 



— addr 
A user variable 



input buffer* 



IM! 



addr b — 

Complements the 8-bit contents of addr by the bit pattern of byte b* 



TRAVERSE 




addrl n — addr2 

Moves across the name field of a fig-FORTH variable length name field* addrl is the 
address of either the length byte or the last letter* If n=l, the motion is toward the 
end of the name? if n=-l, the motion is toward the length byte* The addr 2 resulting is 
the address of the other end of the name* 



scr 



Displays on the selected output device the three screens which include that numbered scr, 
beginning with a screen evenly divisible by three* Output is suitable for source. text 
records, arid includes a reference line at the bottom taken from line 15 of screen 4* 



TYPE 



addr n — 

Transmits n characters starting at addr to the screen* No action occurs if n=0* Vectors 
to AESJRT if the break key is pressed. 

ul u2 — ud 

Performs an unsigned Multiplication of ul by u2, leaving the unsigned double number 
product ud. 



U/ 



ud ul — u2 u3 

Leaves the unsigned remainder u2 and unsigned quotient u3 from the unsigned double 
dividend ud arid unsigned divisor ul. 



IK 



ul u2 - f 

Leaves a true flag if unsigned 16 bit value ul is less than unsigned 16 bit value u2*, 
otherwise leaves a false flag. 
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UNTIL 



f — (run-time) 
addr n — (compile) 
Occurs within a colorr-def inition in the form** 
BEGIN ♦ ** UNTIL 

UNTIL Marks the end of a BEGBHMIL loop, At run-time, UNTIL controls the conditional 
branch back to the corresponding BEGIN* If f is false , execution returns to just after 
E£GIN; if true, execution continues beyond UNTIL • 



At compile-time, UNTIL compiles the run-tine ( OBRANCH ) arid an offset fro* i- 
n is used for error tests* 



E to addr* 



UPDATE 



Harks the most recently referenced block (pointed to by PREV) as modified ♦ The block will 
subsequently be transferred automatically to disk should its buffer be required for 
storage of a different block, or upon execution of FLUSH* 



USER 



A defining word used in the for*** 
n USER cccc 

which creates a user variable cccc* The parameter field of cccc contains n which is the 
cell offset relative to the user pointer (register UP) for this user variable* When cccc 
is later executed* it places the absolute user area storage address for cccc on the stack? 
it is at this address that cccc's "value" is kept* 



VARIAEtE 



MUST 



A defining word used in the form! 
n VARIABLE cccc 

When VARIABLE is executed, it creates a dictionary for cccc and allots 2 bytes in cccc's 
parameter field for storage} the contents of these 2 bytes is initialized to n* Hhen cccc 
is later executed, the address of its parameter field (containing n) is left on the stack, 
so that a fetch or store nay access this location* 



Lists the names of the definitions in the CONTEXT vocabulary* "Eireak" will terminate the 
listing* The listing will continue into the CONTEXT vocabulary's parent vocabulary* (See 
the user manual section on the linking system*) 



VdC-LBK 



A user variable containing the address of the vocabulary link field in the definition of 
the most recently created vocabulary* All vocabulary names are linked by these fields to 
allow control for FORGETting through multiple vocabularies* 
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VOCABULARY — 

A defining word used in the form** 
V0CAE1LARY cccc 

to create a vocabulary definition cccc* Subsequent execution of cccc will hake it the 
CONTEXT vocabulary which is searched first by INTERPRET* The seqier.ce "cccc DEFBaTEONS" 
will also nake cccc the CURRENT vocabulary into which new definitions are placed* 

In fig-FORTH, cccc will be so chained as to include all definitions of the vocabulary in 
which cccc is itself defined (a "child/parent" relationship is thus establihed between 
cccc and the vocabulary in which it is defined)* All vocabularies ultimately chain to 
FORTH ♦ By convention* vocabulary names are to be declared IMMEDIATE* See UOC-LINK* See 
the user manual for a description of the stricture of a vocabulary definition* 

WARNING — addr 

A user variable containing a value controlling messages. If = 1 then error messages are 
taken from disk* arid screen 4 of drive 0 is the base location for messages* If = G* 
messages will be presented by number* If = -li executes (AP-ORT) for a user specified 
procedi.fr e* See MESSAGE* ERROR* 

WHILE f — (run-time) 

addrl ml — addrl nl addr2 n2 (compile-time) 
Occurs in a colon-definition in the form** 
BEGIN *** WHILE (tp) **♦ REPEAT 
At run- timet WHILE selects conditional execution based on boolean flag f* If f is true 
(non-zero), WHILE continues execution of the true part through to REPEAT, which then 
branches back to BEGIN* If f is false (zero), execution skips to just after REPEAT* 
exiting the structure. 

At compile time, WHILE compiles OBRANCH and leaves addrZ of the reserved offset* The 
stack values will be resolved by REPEAT. nZ is used for error checking* 

WIDTH — addr 

A user variable containing the maximum number of letters saved in the compilation of a 
definitions' name. It must be 1 thru 31* with a default value of 31* The name character 
count and its natural characters are saved, up to the value in WIDTH. The value may be 
changed at any time within the above limits. 

WORD c — 

Reads the next text character from the input stream until a delimiter c is found, and 
stores the packed character string beginning at the dictionary buffer HERE* WORD leaves 
the character count in the first byte at HERE, then leaves the characters, and ends with 
two or more blanks* Leading occurrences of c are ignored* If BLK is zero, text is taken 
from the terminal input buffer, otherwise from the disk block whose number is stored in 
BLK. See BLK, IN* 

X — 

This is a pseudonym for the "null", i*e* a dictonary entry for a name of one character of 
AT ASCII null. It is the execution procedure to terminate interpretation of a line of text 
from the terminal or within a disk buffer, as both buffers always have a null at the end. 
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XOR nl rtZ — r»3 

Leaves the bitwise logical exclusive-or (ri3) of two values (nl 9 nZ)« 



Used in a colon-definition in form** 

♦ xxx C words 3 wore J 
Ends compilation arid sets the execution node* The words after C are executed, not 
compiled* (This allows the user to perform calculations or make compilation exceptions 
before resetting compilation with ]♦) See LITERAL, ]♦ 

[COMPILE] — 

Used in a colon-definition in form** 

- ! xxxx [COMPILE] FORTH } 
[COMPILE] will force the compilation of an immediate definition, which would otherwise 
execute during compilation* The above example will select the FORTH vocabulary when xxxx 
executes, rather than at compile time* 



] — 

Sets the compilation mode 4 , text from the input stream is subsequently compiled* See [. 
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This section includes about ninety words, which can be divided into five groups J Graphics arid 
sound words, controller arid player/missile graphics words, IOCB words, words from the DEC User's 
Group, and a few Miscellaneous words* Source code for host of these words is included on the Coin-Op 
FORTH boot disk for the user's convenience; the words are already in the boot, however* (The source 
code is in highly compressed form and is best used with the formatted printer words, Section KM*) 

The following discussions are aimed at familiarizing the user with the main words in this 
section* Some of the words are not discussed, however, so browsing through the glossary, which is 
complete, could be quite worthwhile* 

Graphics arid Sound 

Graphics ^ 

Read chapter 9 of the Basic Reference Manual (Graphics Modes and Commands) and chapter 3 of De 
Re Atari (Graphics Indirection arid Character Sets); the latter will give you an idea of how color 
registers work, while the former lists the specific Atari graphics commands* Coin-Op FORTH uses the 
same graphic commands as Atari BASIC (using post-fix notation, of course! )♦ 

The main graphic commands are as follows** 
GRAPHICS GR* 
t COLOR C* 
DRAWTO DR. 
LOCATE LOC* 
F10T PL* 
POSITION POS* 
PUT , GET 
SETCOLOR SE* 
XI01S 

See the glossary for an explanation of how these words work in Coin-Op FORTH* The glossary also 
contains graphics primitives and a number of constants which return the addresses of OS and hardware 
graphics registers* 

Sound 
■ 

Read chapter 10 (Sound) of the Basic Referene Manual and chapter 7 (Sound) of De Re Atari for an 
explanation of sound on the Atari* 

The only Coin-Op FORTH sound word is SOUND, which operates exactly like the BASIC command except 
that it uses post-fix notation* See the glossary entry below* 



Controllers and Player /Missiles 

Controllers 

Read chapter 10 (section on controllers) in the Eiasic Reference Manual for a discussion of 
controllers* 



Coin-Op FORTH uses the controller words'. 
PADDLE 
PTRIG 
STICK 
STPJG 

These work like their BASIC counterparts* See the glossary entries below for an explanation* Note 
also that the constant CONSOL returns the address of the register which reads the START, SELECT, and 
OPTION buttons. 



Player/Hissiles 




Read chapter 4 (Player - Missile Graphics) of De Re Atari for an emanation of how players arid 
Missiles work* 

Coin-Op FORTH includes the following player /Missile wordst 
COLPti! - sets the color of a player 

KTOS! - sets the horizontal position of a player or Missile 
PBASE - returns the base address of player/Missile DMA 
SIZE! - sets up player/Missile graphics* 

In addition, the following constants return the addresses of registers which are useful in 
Manipulating player /Missiles (consult the Atari OS and Hardware Manuals for an explanation)'* 
DMACTL, GRACTL, PRIOR. 

Consult the glossary below for descriptions of how to use these words. 

Creation of the actual player/Missile (through storing values into player/Missile MeMory) is 
left to the user, who will no doubt find C! and OWE (in the Coin-Op FORTH kernel) to be very useful 
comands* 



IOCB WORDS AND CIO 

These words are used to set up I/O control blocks! these blocks in turn are used to perforM I/O 
with a variety of devices. Ho atteMpt will be Made here to describe in detail the various devices, 
coMMands, arid forMats used in this process. The user should read De Re Atari chapter 8 (Operating 
SysteM) and the OS Manual section on I/O in order to gain such knowledge. 

I/O is perforMed by setting up an IOCB (there are 10 of theM, each with 16 bytes) and executing 
the OS CIO routine. Coin-Op FORTH facilitates this process by providing the user with a number of 
words with which to handle IOCBs. 

First, the user selects an IOCB #n to operate on by executing 

n IOCB 

where n is the nuMber of the IOCB which is to be used. The words ICDNO , ICCOM , ICSTA , ICBAL , 
ICBLL , I1CAX , I2CAX , AND ICPTL will then return to the user the addresses of various entries in 
IOCB * n. For example, 0 IOCB I1CAX will return the address of the first auxiliary information byte 
in IOCB *0 (which handles the screen editor)} 3 IOCB ICBLL will return the address of the buffer 
length cell in HSCB *3. 

These addresses can then be used to set up the IOCB. I4hen this is eonplete, execution of the 
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word CIO will perform the desired I/O operation* (A related word, AGIO, is used in certain 
circumstances to send a single character to a device through the 6502 accumulator J see the 
glossary*) OPEN and CLOSE nay be used to open and close the currently selected IOCBJ PUT and GET 
will put and get characters to arid from the device specified by the current IOCB* 



DECUS 

These words were written by the DEC Users Group, and perform some useful operations* 

OSET sets a memory location to 0* 

1+! , 1- , arid 2* do exactly what me would expect* 

ALLOC functions like ALLOT, but it reserves cells rather than bytes* ARRAY and TBL are defining 
words used to create tables* See the glossary for details* 

BDUrF arid \ are used in conjunction with each other* 
addrl addr2 BDUMP 

will cause 2 digit hexadecimal representations of the contents of each byte from addrl to addr2 to be 
placed on the screen* The routine places the first 8 values on one screen line, then performs a 
carriage return arid places the next 8 on the next line, and so on* At the start of each line, EOUMP 
also prints the address (in hexadecimal) of that line's first byte, arid at the end of each line the 
routine points the FORTH word \ ♦ V f '.in turn, takes an address arid 8 values on the stack - 
precisely the format in which BDUMP has printed out its data* \ then takes the low byte of each 
value arid stores it into Memory, starting at the address on the bottom of the stack* It ends with a 
QUIT, which performs a line-feed without printing out "oK"* 

Thus, it is possible to make use of the Atari screen editor to move the cursor over a line which' 
BDUMP has printed out and type over the values which are printed on that line 4 , when a [RETURN] is 
then performed, these values will be written into memory at the locations which were read by BDUMP* 
Furthermore, data printed by BDUMP on subsequent screen lines will not be damaged by n oK n s, since 
QUIT is used to exit* This is a clever and powerful interactive tool* try it for yourself to see how 
it works* 




Miscellaneous 

These include a number of OS and hardware constants (i*e*, constants which return the addresses 

of OS and hardware registers), the historically obsolete constants LPWORDS arid FORMY (used to 

indicate where the screen code of printing and code formatting words lay on disk), arid the word 
SAVENFAs, 

Read through the glossary to discover which OS arid hardware constants are available - these are 

quite useful t and most of them are used by various graphics routines* 

SAVENFAs takes the vocabulary entry pointers stored in the F01\TH vocabulary and saves them in 
the boot parameter area (the 30 or so bytes after the "origin" , which is at $D00)1 This will 
prevent a cold start (see COLD) from "forgetting" any non-booted words which the user has added. It 
is used by HTOBJ* 



♦IOC 



A defining word used in the form*" 
n *I0C cccc 

Creates a header for cccc and places the value n in cccc's parameter field* When cccc is 
later executed it returns the address of the memory location which is n bytes above the 
first byte of the "current" IOCB. See IOCB* 



OSET 



addr — 

Sets the 16-bit value at addr to 0» 



1+! 



addr — 

Increments the 16-bit contents of addr by 1« 



1- 



n — n-1 
Subtracts 1 fro* n. 



2* 



nl - n2 

Hultiplies nl by 2* leaving the product n2* 



ACIO 



Places n in the 6502 accumulator arid calls CIO, which will use the I(X8 previously 
selected by the user (see IOCB)* Assumes that the IOCE; is already set up* Can be used to 
send a single character to a device* Normally used with ICBLL set to zero* 



ALLOC 



n 



Reserves n cells in the dictionary (i*e* t advances the dictionary pointer by 2n bytes)* 



ARRAY 



A defining word used in the form** 
n ARRAY cccc* 

Creates a dictionary entry for cccc arid reserves n cells (n*2 bytes) as cccc's parameter 
field* Later execution of cccc returns the address of the first cell in this parameter 
field* This address may then be used to store and retrieve values in the parameter field* 



ATACHR 



— addr 
A constant which 
written to the 



the AT ASCII value of the character most recently read from or 
or the value of the most recently plotted or read color pixel* 



AUDCTL 



— addr 

A constant which contains the address of the audio mode control register 



BOTSC 



— addr 

A constant which contains the address of the split screen register ($2BR* If the 
contents equal 4* split screen text is enabled; if they equal 23* full screen text is 
enabled* 
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BDUMP addrl addr 2 — 

Displays the contents of memory addresses addrl through addr2, byte by byte, on the output 
device* The contents are displayed in a 2 digit hexadecimal representation* with 8 values 
per screen line} the address of the first byte on a given line is printed at the beginning 
of that line, arid each line ends with the word \, which allows memory locations in the 
"dumped" area to be easily altered* See \ arid the user manual section on DECUS words* 

C* n — 

Sets the color register (pixel data to be used in subsequent plotting* drawing* and 
printing) to n* n ranges from 0 to 4* 

ClAUD — addr 

A constant which contains the address of the audio control register for audio channel 1 
($D20D* 

C2AUD — addr 

A constant which contains the address of the audio control register for audio channel 2 
($D203)* 

C3AUD — addr 

A constant which contains the address of the audio control register for audio channel 3 
($D205h 

. 

C4AUD — addr 

A constant which contains the address of the audio control register for audio channel 4« 
($D207) 

CH — addr 

Returns the address of the register which contains the ATASCII value of the most recently 
pressed key* ($2FD* 

CH? addr — 

Converts the 8-bit contents of addr to a 2 digit hexadecimal value* and sends this value 
to the output device* 

CHBAS — addr 

A constant which contains the address of the register which contains the most significant 
byte of the starting address of the current character set* ($2H)* 



CIO 



cm n — 

Types the least significant byte of n as a 2 digit hexadecimal number* (E*g* $0014 CHH 
types 14} $FF23 CHH types 23)* 



Calls the Atari CIO routine, using the "current" IOCB* This assumes that an IOCB has been 
selected using n IOCB and that IOCB *n has been set up properly* (This can be done using 
the words defined by *I0C, after n IOCB has been executed)* 



CLEAR 



Clears the screen* 
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CLOSE 




* - 




Closes the currently selected IOCB. n IOCE: Must be performed before calling CLOSE* Do 
not attempt to close IOCB * 0, as this controls the screen editor* 



CN n — 

An alias for CONSTANT. 

COLO — addr 

A constant which contains the address of the playfield color register for playfield color 
0. <$2C4)* 

COL1 — addr 

A constant which contains the address of the playfield color register for playfield color 
U (*2C5) 

C0L2 — addr 

A constant which contains the address of the playfield color register for playfield color 
2* ($2C6)* 

C0L3 — addr 

A constant which contains the address of the playfield color register for playfield color 
3* <$2C7)* 

COL4 — addr 

A constant which contains the address of the playf ield color register for playfield color 
4. (*2C8)* 

Alias for C. 

COLPM — addr 

A constant which contains the address of the first player /nissile color register (i.e*, 
the byte corresponding to player 0)* ($2C0)* 

COLPH! c n — 

Sets the color of player n to c, where the highest 4 bits of c indicate the color (0-15) 
and the lowest 4 bits indicate the luminance (0-15, although the lowest bit is not 
actually read so that luminances 0 and 1 are the same, as are 2 and 3, etc*)* n=0 to 3* 
Missile tn will have the sane color as player#0, and so forth* unless the "five player" 
option is enabled* See De Re Atari* 

CQNSQL — addr 

A constant which contains the address of the register which reads the console switches 
START, SELECT, OPTION. ($D01F) 



CRSINH — addr 

A constant which contains the address of the cursor inhibit register ($2F0)* When the 
contents equal 0, a cursor is displayed on the display screen. 
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Color 



— addr 

A variable which contains the nunher of the color register to be used in drawing and 
printing* 



DLST 



— addr 

A constant which contains the address of the OS shadow of the register which contains the 
starting address of the display list* ($230)* 



DMACTL 



— addr 

A constant which contains the address of the OS shadow of the DMA control register* 
($22F)* Alias for DMCT* 



DMCT 



— addr 

A constant which contains the address of the OS shadow of the DHA control register* 
($22F)* 



DR* 



X y — 

Draw a line frow the ojrrent cursor position to x*y* in the color previously selected 
(using SETCOLOR and COLOR)* 



DRAWTO 



F1AUD 



Alias for DR* 



addr 



A constant which contains the address of the audio frequency control register for audio 
channel 1* ($D200)* 



F2AUD 



— addr 

A constant which contains the address of the audio frequency control register for audio 
channel 2* ($D202)* 



F3AUD 



F4AUD 



— addr 

A constant which contains the address of the audio frequency control register for audio 
channel 3* <$D2(W)* 



addr 



A constant which con tains the address of the audio frequency control register for audio 
channel 4* ($0206)* 



FILDAT 



— addr 

A constant which contains the address of an OS register 
operations* 



which holds data used in fill 



XI ♦ 3 A t sr i Extent i ons t Glossary * p ♦ 5 



FORMY 



— 39 

Returns decimal 39, which historically was used as the starting screen of a code 
formatting program ♦ 



GET 



Gets one character from the device specified by the "current" IOCB and leaves it on the 
stack. Assumes that the IOCB is set up (except for the command byte) prior to the call to 
GET* 



GR. 



n 



Clears the current screen, opens the graphics screen using graphics mode n. Add decimal 
16 to n to allow full screen graphics (i.e>i no text window*, this can only be used during 
program execution when no screen editing functions are necessary). Add decimal 32 to n to 
prevent the screen from being cleared. 



GRACTL 



addr 



A constant which contains the value of the graphics control register. ($D01D). 



GRAPHICS 



n — 
Alias for GR. 



Get 



n 



A machine code routine which gets one piece of informaton from the device specified by the 
"current" IOCB arid leaves it on the stack. The IOCB must be set up before Get is called. 



H? 



addr — 

Converts the 16-bit contents of addr to a 4 digit hexadecimal value, and transmits this 
value to the output device. 



HD 



n - 



Types the single character representation of n, as if BASE were set to n+1 (e.g. 5 HD 
types 5, 15 HD types F, 35 HD types Z). 



HH n — 

Converts the 16-bit value n id 3 A digit hexadecimal value, and transmits this value to 
the o«.rtpLit device. 

HPOS! H n — 

Sets the horizontal position of player n to x. n = 0 to 7 (missile 0 = player etc.). 

x = 0 to 255. 
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— addr 
Defined by *I0C* 
"current" IOCB* 



Returns the address of the first auxilliary information byte in the 



I2CAX 



— addr 

Defined by *I0C* Returns the address of the second auxilliary information byte in the 
"current" IOCB* 



ICBAL 



— addr 

Defined by *I0C* Returns the address of the low byte of the buffer address entry in the 
"current" IOCB* 



ICBLL 



— addr 

Returns the address of the cell which contains the buffer length entry in the "current" 
IDCB. 



ICCOM — addr 

Defined by ♦IOC* Returns the address of the coward byte of the "current" IOCB* 



ICDNO 



addr 



Defined by *I0C* Return the address of the device * byte of the "current" IOCB* 



ICPTL 



— addr 

Defined by *I0C* Returns the address of the "put character entry pointer" in the 
"Djrrent" IOCB* This is only used by BASIC* 



ICSTA 



— addr 

Defined By *I0C* Returns the address of the status byte of the "current" IOCB* 



IOB 



— addr 

A variable which contains an off set from the first byte of IOCB * 0 to the first byte of 
the IOCB which is currently selected* See IOCB* 



IOC 



A variable which contains the starting address of the IOCB ojrrently selected by the user 
^.0 i~ i ♦ 



IOCB 



n — 

Sets the "current" IOCB to IOCB * n* 



(This changes the values in IOC and IOB)* 



LHARGN 



— addr 

Constant which contains the address of the register which contains the left margin value 
($52)* 



NOPLY 
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LOC* x a — n 

Gets the value of the pixel on the screen at position x,y, arid positions the graphics 
cursor at this point* n will indicate which color register the pixel's color is taken 



LOCATE x 3 — H 

Alias for LOC* 



LPWORDS — 37 

Historically, line printer words were placed on screen 37 (decimal)} LPHORDS returned the 
starting screen nunber so one could write LPHORDS LOAD* 



Disenables player/ttissile DMA arid sets the player/ttissile size and position registers to 
0* (This does not stop the player /Missile DMA cycle steal, however, as DMACTL is left 
intact • ) 



OPEN nl n2 n3 — 

Opens the "current" IOCB, using the pararteters on the stack* nl is the value to he stored 
in ICAX2, n2 is the value to he stored in ICAX1, and n3 is the buffer address (the buffer 
should contain an AT ASCII string by which CIO will identify which device is being linked 
to the I0CB in question 4 , see the Atari OS Manual for details)* 



PADDLE nl — n2 

Reads paddle nl (nl = 0 to 7), returns paddle position n2 (n2 = 0 to 256)* 



PBASE 



Returns the address of the player/Missile DMA area* This value is set by GRAPHICS and 
changes with different nodes* 



PL* x y — 

Plots a point in the color last selected (using SETCOLOR and COLOR cottnands) at screen 

position x,y* 



F1AYER n — 

Sets up player /Missile DMA (by setting PBASE, GRACTL, and DMACTD* n = 1 
resolution; n=2 for double line resolution* See De Re Atari* 



F10T x y — 

Alias for Fl* 



SAMENFAs 
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PMBASE — 3ddr 

A constant which contains the address of the hardware register which holds the most 
significant byte of the base address of the player /missile DHA area* ($DW)* 



POSi k a — 

Sets the current graphics cursor position to x,y* (0,0 is the top left corner of the 
screen) ♦ Does not plot any points* 



POSITION x y — 

Alias for POS* 



PRIOR — addr 

Returns the address of the hardware priority register (GPRIORJ $DW8)# 



PTRIG nl — n2 

Reads paddle trigger nl (nl = 0 to 7), returning n2 where n2 = 0 indicates trigger- 
pressed, ri2 = 1 indicates trigger not pressed* 



PUT n — 

Puts the character with ATASCII value n at the current cursor position on the screen* 



Qhase — n 

A variable which contains the address of the player /missile base* See De Re Atari, 



Returns a random number n on the stack, where n ranges from 0 to 255* (This value comes 
from hardware timer SKRES)* 



— addr 

Returns the address of the first byte of system timer 1 ($14). This is a three byte 
timer ♦ 



St — addr 

A variable which contains the ATASCII characters "S" and n l n $ The address of this 
variable is used as the buffer address in an "open" call to CIO and indicates that the 
device being opened is the graphics screen* 



tfoves the NFAs in the vocabulary entry pointers of the FORTH vocabulary to the boot 
parameter area (starting at $D22)J after this is done, a cold start ( COLD ) will not 
erase any words defined prior to the execution of SAVENFAs from the dictionary* 
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SPB 



SE* fli n2 n3 — 

Sets color register nl+1 to hold color n2 with luminance n3. 



SETCOLOR Til n2 n3 

Alias for SE. 



SIZE! s n — 

Sets the width of player n to s, where s = 0 or 2 indicates normal width, s = 1 indicates 
double width, and s = 3 indicates quadruple width* n = 0 to 4} all Missiles are set by n 
= 4. 



SKCTL — addr 

A constant which contains the address of the serial port contol register ($D20F) which 
controls the configuration of the serial port as well as the Fast Pot Scan arid the 
Keyboard Enable Functions* 



SOW© n p d v — 

Sets audio channel n (n = 0 to 3) to have pitch p (p is actually a divisor*, see the Basic 
Reference Manual for pitches corresponding to a given p), distortion d, and vol we v# 



Sets the base address of the player/Missile DMA area and HIMEM (the highest available 
dictionary address, which is $17F bytes above the player /fissile base address)*, the PM 
base address nust fall on a 2K boundary* 



STICK nl — n2 

Reads joystick nl (nl = 0 to 3) and returns n2, where n2 indicates which direction the 
stick is being pushed* See the Basic Reference Manual for these values. 



STRIG nl — r»2 

Reads joystick trigger nl (nl = 0 to 3) arid returns n2, where n2 = 0 indicates trigger 
pressed and n2 = 1 indicates trigger not pressed* 



A defining word used in the for*** 

TBL cccc nl , ri2 , n3 , ♦♦♦ 
TBL creates a header for "table" cccc*, values nay then be stored into cccc's parameter 
field* When cccc is later executed, its PFA is returned on the stack, allowing the user 
to then index values in the parameter field* Used to create date tables at compile tine* 
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VDELAY — addr 

A constant which contains the address of a hardware register which is used to "delay" the 
appearance of a player or missile by 1 scan line* This is useful when two-line player 
resolution is used* ($D016)* 



XI018 n — 

Fills an area of the screen using the color in color register n« 

in the Basic Reference Manual ♦ 



• )<-p 



\ 




addr nO nl h2 ri3 xA rfi n6 n7 
Takes the low byte of each stack value nO , nl i ♦ ♦ ♦ t n7 » and stores those bytes in memory 
beginning at addr* nO is stored at addr+O* nl is stored at addr+l, etc* This is used in 
conjuncton with BDUMF" to facilitate rapid alteration of the contents of an 
See BDUHP arid the discission of DECUS words before this glossary* 
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II.4 THE FIG EDITOR 

The usual way of entering the fig Editor is by using n EDIT, which sets up editing on screen n* 
The cowand words in the fig Editor can be divided into three groups'* screen editing words, line 
editing words, and words frow the FORTH vocabulary that are useful for editing* The conaands in 
these three groups are listed below? 

Screen Editing Cowhands 
UL LL DOIT 

Line Editing Demands 
HL DL IL RL CL SL SL TL * 1 

Other Dottnartds 

L N COPY SHOW LIST WHERE 
The cursor control (arrow) arid editing (Clear, Insert, Delete) keys are also used in the fig Editor ♦ 

Screen Editing Words 

There are three screen editing words in the fig Editor: UL and LL clear the display screen and 
list the 'upper' or 'lower' (first or last) 16 lines of the current screen. The third word, DOIT, 
causes the contents of the top 16 lines of the display screen to be copied to the appropriate half of 
the screen buffer and Marks that buffer as updated* For convenience, UL and LL print the word DOIT 
two lines below the 16 lines that they list* To use the screen editor, do a UL or LL (depending on 
which half of the current screen you want to work on) , then use the arrow arid editing keys to change 
the information on the top 16 lines of the display* When you are finished editing that half-screen, 
register the changes by moving the cursor to the line with DOIT on it and hitting [RETURN] ♦ An 
Important Note: don't hit [RETURN] while you are on the top 16 lines of the display* If you do, the 
interpreter will try to interpret the stuff you are editing* Use the arrow keys to move from line to 
line instead* 



Line Editing Words 

Most of the fig line-editing cow-ends involve nerving lines back and forth between the current 
screen and the pad* IL, DL, HL, RL, and CL all fall into this category (thou* CL copies a specified 
line from another screen to the pad)* SL and BL put a blank line on the current screen, but in two 
different ways** SL Moves the lines below the new blank line down to hake roott for it, while El just 
overwrites the specified line with blanks* % and % both put the text following then onto the screen 4 * 
$ puts it on the specified line} I puts the text on the line after the specified line, pushing the 
lines below it down to wake rooM* TL sets up editing of a specified line by typing the line with the 
line nuriber and a $ preceding it (it also copies the line to the pad)* This way, you can TL a line, 
edit it with the arrow keys, and put the edited line back by just hitting [RETURN] (since the line 
nunber and % are already there) ♦ 

Except in certain situations (inserting lines onto a screen that already has text on it, for 
example), the line editing cowards are not as useful as the fig screen editor, since moving a cursor 
around and. waking changes on the screen are easier than typing lots of corwands* 
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Other Editing Words 

There are also some words trtm the FORTH vocabulary that are useful for editing* LIST and SHOW 
are good for looking at one or wore screens (to find a certain word, for example)* COPY, as its name 
implies, copies the contents of one screen to another* L lists the current screen* N lists the next 
screen* WHERE is useful for finding errors in a screen that won't LOAD* Typing WHERE after 
compilation halts will print the screen number and the text of the line where the compiler stopped, 
with a caret indicating exactly where the error was found* 



The normal way of exiting the fig Editor is with FLUSH, which resets the screen margins, copies 
updated screens to disk, and puts the system back in the FORTH vocabulary* 



♦OFLBCS — r. 

Returns the number of lines per editing screen (32) * 

-MOVE addr n — EDITOR 

Moves a line of characters that starts at addr to line n of the current edit screen* 
Marks the current screen as updated* 

$ n — EDITOR 

Puts the text following $ on line n of the current edit screen* Marks the screen as 
updated* 

7. n — EDITOR 

Puts the text following % after line n of the current edit screen* The lines below line n 
are pushed down to make room (the last line of the screen is lost)* Marks the screen as 



El n — EDITOR 

"Blank lire*" Replaces line n of the current edit screen with blanks* Marks the screen 

as updated* 

COPY nl ri2 — FORTH 

Copies the contents of screen nl to screen n2 on the disk* 

CL nl n2 — EDITOR 

"Copy line*" Copies lire nl of screen n2 to the pad* The current edit screen number does 

not change* 



DL n — 

"Delete line*" Deletes line n from the current edit screen, Moving the lines below the 
deleted line up* Saves the deleted line in the pad and marks the screen as updated* 

DOn — EDITOR 

Causes the top 16 lines of the display screen to be copied to the screen buffer* If 
TOPFLAG contains $0, the display is copied to the 'upper' half (first 512 characters) of 
the buffer? if TOPFLAG contains $200, the display is copied to the 'lower' half (last 512 
characters) of the buffer • The buffer is then marked as updated, the screen is cleared, 
and the top 16 lines are reprinted* 
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r. — FORTH 

Sets up editing of screen n by establishing EDITOR as the CONTEXT vocabulary and setting 
SCR (the current editing screen) to n. 

— FORTH 

Makes EDITOR the CONTEXT vocabulary* It will then be searched first when the input stream 
is interpreted* The EDITOR vocabulary contains screen- and line-editing functions* 

— EDITOR 

The EDITOR version of FLUSH resets the screen Margins to (left) 2 and (right) 38, 
establishes FORTH as the CONTEXT vocabulary, and Moves updated blocks fro* buffer to disk* 

n — EDITOR 
"Hold line*" Copies line n of the current edit screen to the pad* 

n — EDITOR 
"Insert line*" Inserts the lire in the pad after line r» of the current edit screen* 
pushing the lines below it down (arid losing the last line of the screen)* Harks the 
screen as updated* 

— FORTH 

Lists the current editing screen (screen number is obtained fron S£Rh 



n — addr FORTH 

Returns the starting address in disk buffer of line * n of the screen currently being 
edited* If the line is not on the screen (ri>32) # an error Message is printed* 

n — FORTH 

Lists the contents of screen n with the Margins set to (left) 2 and (right) 38* The 
nunber of each line is printed at the beginning of that line* 

— EDITOR 
Clears the display screen and displays the lower half of the current edit screen on the 
top 16 lines* The word DOIT is printed two lines below the half-screen for the user's 
convenience* 



— FORTH 
Lists the contents of the next screen 
contents of SCR by D* 



(screen nunber is obtained by increwenting the 



n — EDITOR 
"Replace line*" Replaces line n of the current edit screen with the lire in the pad* 
Marks the screen as updated* 



nl rtZ — FORTH 
Lists the contents of screens nl to rt2, inclusive! 

n — EDITOR 
"Spread line*" Creates a blank line n on the current edit screen by pushing all of the 
lines below it down* The last line of the screen is lost* Harks the screen as updated* 



— FORTH 

Hoves the next line in the input streaM to the pad; the line will end with a series of 
blanks* 
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TOPFLAG 



UL 



n — EDITOR 
"Type line*" Copies line n of the current edit screen to the pad, then types the line 
with the line nunber arid the word $ preceding it. The line number and $ are there to 
facilitate changes to the line* 

— addr EDITOR 

A variable used by the editor to keep track of which half of a screen is being edited* 

Contains $0 if it's the 'upper' half (first 16 lines) or $200 if it's the 'lower' half 
(last 16 lines)* 



— EDITOR 
Clears the display screen arid displays the upper half of the current edit screen on the 
top 16 lines* The word DOIT is printed two lines below the half-screen for the user's 
convenience* 



ULL 




n — EDITOR 

Clears the display screen and displays one half of the current edit screen on the top 16 
lines* The screen offset* n, determines which half is displayed ($0 for the 'upper' half, 
$200 for the 'lower' half)* The screen margins are set to (left) 3 and (right) 34 • The 
word DOIT is printed two lines below the half -screen for the user's convenience* 

rtf n2 — FORTH 

After compilation of FORTH code stops due to an error, the block * n2 and an offset nl 

from the start of the block to the point where the error was detected are left on the 

stack* Subsequent execution of Hf€RE will print the block * and the line on which the 

error was found; EDITOR is then established as the CONTEXT vocabulary and SCR is set to 
the block *♦ 



( 
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The Atari computer contains a 6502 Microprocessor arid FORTH provides easy access to its assembly 
language. This section does not explain assembly language programing in general or the 6502 
instruction set in specific. There are good books available on the subject which should be consulted 
first. This is intended to explain assembly language programming in FORTH, with a general discussion 
of the instructions specific to the FORTH assembler and how they are used. 

Syntactical differences : Like the rest of FORTH, the assembler uses reverse polish notation. In 
standard assembly language programming the syntax ist 

Cop-code mnemonic] [addressing model [operand] 
e.g. LDA tO or STA (addr), Y ♦ With the FORTH assembler these appear in the order 
[operand] [addressing mode] [op-code] 

e.g. 0 *LDA, or addr )Y STA. Naturally, to accomodate this change there are certain 
particular ways of writing the address modes that are not found in standard 6502. These are: 

.A -accumulator mode t X -indexed with X 

,Y -indexed with Y X) -indexed indirect with X )Y -ind. indir. with Y 

The immediate mode is the same*. * ♦ Also, one need not write only one operation per line. 

Op-code changes *. There are differences in the appearance of 6502 op-code mnemonics used by the FORTH 
assembler} an alphabetic list of these differences appears below. Each op-code mnemonic has a 
comma affixed to its end. E.g. ADC becomes ADC, . This sets off what would normally be one 
line of assembly code arid helps to differentiate assembler words that might be interpreted as 
hexadecimal numbers, such as ADC ♦ Also, V compiles into the dictionary, so the comma here 
indicates the point at which code is generated. 

Conditionals 4 . One thing missing from the FORTH assembler vocabulary is the set of standard branch 
statements such as BCS or BEQ. Instead, this ASSEMBLER vocabulary is equipped with conditional 
structures analogous to those in the FORTH vocabulary, including BEGIN , - UNTIL, loops and IF, - 
ELSE, - ENDIF, . The comma serves to differentiate these words from those in the FORTH vocabulary. 
With these conditionals comes a set of tests which specify branching by the conditionals which follow 
them. For example, 

CS IF, ELSE, 

will generate a branch to the code following the IF, if the carry status bit is set, hut will 
generate a branch to beyond the ELSE, if not. Other such tests include 

0= 0< MS >= 

NOT reverses the result of any test appearing 4 , for example, CS NOT IF, executes the code following 
IF i if the carry status bit is not set. This method of branching eliminates the need for labels 
within assembly code . 

CODE and CI *♦ It is possible to write assembly code when not in the ASSEMBLER Vocabulary by using 
the defining word CODE . CODE changes the CONTEXT vocabulary from CURRENT to ASSEMBLER making 
available the assembler op-code mnemonics* At the end of a CODE definition the word CJ is used, 
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returning CONTEXT to CURRENT ♦ CODE lets one name assenbler words as if they were in FORTH* 

XSWE t The 6502 x register contains the FORTH parameter stack pointer ♦ When the x register is 
being used in an assembly code definition for other purposes it Must be saved elsewhere and restored 
before leaving ASSEMBLER* XSAUE leaves the address of a zero-page buffer for storing the x 
register* It appears in assembly definitions in the forn XSAVE STX, and XSAVE LDX, ♦ 

NEXT and return of controls ! NEXT is a constant which returns the address of the FORTH address 
interpreter, a subroutine that Moves execution frott one definition to the next. At the end of a 
CODE definition control Must be returned to NEXT (i»e«i NEXT JHP,) or to another routine which 
returns to NEXT such as POP , PQPTHQ f PUSH , and PUT (see the glossary for details on these words). 

The glossary that follows contains the instructions used by the Atari FORTH assenbler « The 
vocabulary in which a word is found appears at its right. Any effects on the stack, either at 
assembly or run-tine are also given along with More detailed definitions and explanations. 

6502 op-code MneMonics as ewployed by the FORTH assenbler J 



one Mode pp-codes. Multi-Mode op-codes 4 . 



BRKi 


CLC, 


CLD, 


CLI, 


CLV, 


ADC, 


AND, 


ASL, 


err, 


CMP, 


DEX, 


DEY, 


INX, 


INY, 


NOP, 


CPX, 


CPY, 


DEC, 


EOR, 


BC, 


PHA, 


PHP, 


Ft A, 


PLP, 


RTI, 


JHP, 


JSR, 


LDA, 


LDX, 


LDY, 


RTS, 


SEC, 


SED, 


SEI, 


TAX, 


LSR, 




Fa, 


ROR, 


SEC, 


TAY, 


TSX, 


TXS, 


TXA, 


TYA, 


STA, 


STX, 


STY, 








t — ASSEMBLER 

Specifies iMMediate addressing Mode for the next op-code generated. 

)Y — ASSEMBLER 

Specifies indirect indexed with Y addressing Mode for the next op-code generated. 

,X — ASSEMBLER 

Specifies indexed with X addressing Mode for the next op-code generated. 

■ 

,Y — ASSEMBLER 

Specifies indexed with Y addressing node for the next op-code generated. 

,A — ASSEMBLER 

Specifies accumulator addressing node for the next op-code generated, 

0< — cc (assembling) ASSEMBLER 

Specifies that the following conditional generate a branch if the previous operation has 
produced a negative result, i.e., the sign bit of the status register is set (s=l). The 
flag cc is left at assembly %im\ there is no run tine effect on the stack. 



II ♦S The Assembler , P * 3 



0= — zz (assembling) ASSEMEtER 

Specifies that the following conditional generate a branch if the previous operation has 
produced a zero result, i*e*, if the zero-bit of the status register is set (z=D* The 
flag zi is left at assembly tine, there is no run-time effect on the stack* 



>= — cc (assembling) ASSEMBLER 

Specifies that the following conditional generate a branch if the zero bit of the status 
register is set (z=l), or if the sign bit is positive (s=0)* It is only correct after 
SUE:, or CMP* ♦ 

ASSEMBLER — FORTH 

Makes ASSEMBLER the CONTEXT vocabulary* It will then be searched first when the input 

stream is interpreted* 

BEGIN, — addrl (assembling) ASSEMBLER 

— (run-time) 

A word in CODE definitions used to nark the start of a loop* Used in the form** 
BEGIN, *♦* cc UNTIL, 

At run-time, it narks the return point for the corresponding UNTIL,* When reaching 
UNTIL,, abranch ack to BEGIN, will occur if the status bit cc left by the conditional 
prior to the UNTIL,, is false*, otherwise execution continues ahead* At assembly tine, 
BEGIN, leaves the dictionary pointer address addr and the value 1 for later testing of 
conditional pairing by UNTIL,* 



BOT — n ASSEMBLER 

Used in code assembly in the form** 

BOT LDA, or BOT 1+ X) STA, 
It addresses the bottom of the parameter stack by selecting the indirect x node and 
leaving n=C at assembly time* n nay be modified to another byte offset into the parameter 
stack* It must be followed by a nulti-node op-code nnemonic* 



CODE — FORTH 

Defining word used in the form* 
CODE cccc ♦*♦ CJ 

Creates a dictionary entry for cccc in the CURRENT vocabulary*, the CFA of cccc contains 
the address of its parameter field, The CONTEXT vocabulary is set to ASSEMEtER, to make 
the assembler mnemonics available* Hhen cccc is later executed the machine code in this 
paraneter field will execute* 



CPU ri — (compiling assembler) ASSEMBLER 

An assembler defining word used to create assembler mnemonics that have only ore 
addressing mode* For example** 88 CPU DEY, creates the word DEY, with its op-code 88 as a 
parameter* Hhen DEY, executes it assembles 88 as a one byte op-code* 
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— cc (assembling) ASSElfLER 
Specifies that the following conditional generate a branch if the carry hit of the status 
register is set (c=0)* The flag cc is left at assembly time? there is no rut-tine effect 
on the stack* 

— (run-time) ASSEMBLER 
addrl 2 — addr2 2 (assembling) 

Occurs within a code definition in the form* 

cc IF, (true) ELSE, (false) ENDIF, 
At run-time ELSE, sets off a section of code that will be executed if the condition 
specified by cc is false* At assembly-time ELSE, assembles a forward jump to just after 
ENDF, and resolves a pending forward branch from IF, ♦ The twos are used for error 
checking of paired conditionals* 

— ASSEMBLER 
A compiling version of UNTIL,* 

— (run-tine) ASSEMBLER 
addr2 — (assembly-time) 

Occurs in a code definition in the form* 

cc IF, (true) ELSE, (false) ENDIF, 
At run-tine ENDIF, marks the conclusion of a conditional structure* Execution of either 
the true or false part. continues after ENDIF,* Hhen assembling addr and 2 are used to 
resolve the pending forward branch to ENDIF,* 

cc — addr 2 (assembly-time) ASSEMBLER 
— addr 2 (run-time) 
Occurs within a code definition in the form* 

cc IF, (true) ELSE, (false) ENDIF, 
At run-time IF, branches based on the condition code cc* If the status bit specified by 
cc is true execution continues ahead* If false a branch is generated to the next ELSE, 
(if present) or to the following ENDIF,* 

Hhen assembling IF, creates a forward branch to an undetermined location based on the 
condition code cc, and leaves addr and 2 for resolution of the branch by the corresponding 
ELSE, or ENDIF,* Conditionals may be nested* 

— addr (assembling) ASSEMBLER 
An array used within the assembler, which holds bit patterns of allowable addressing 
modes* (Do not confuse with INDEX in FORTH vocabulary*) 

— addr ASSEMBLER 
A constant that returns the zero-page address of the Interpreter pointer, specifying the 
next FORTH address which will be interpreted by NEXT* It is used in code definitions in 
the form** 

TP STA, or IP )X LDA, 



nit n2 — (compiling assembler) ASSB&LER 
An assembler defining word used to create assembler mnemonics that have multiple 
addressing modes. For example! 1C6E 60 M/CPU ADC, creates the word ADC, with two 
parameters, When ADC, executes it uses these parameters, the stack values, and the 
contents of HODE to calculate arid assemble the correct op-code arid operand, 

— ASSEffcLER 

Used within the assembler to set HODE to the default value for direct memory addressing, 

zer o-page* 

— addr ASSEHBLER 

A variable used within the assembler, which holds a flag indicating the addressing mode of 
the op-code being generated ♦ 

— ASSEMBLER 

A constant address of an 8 byte utility area in zero-page, See SETUP* 



— addr (assembling) ASSEHBLER 
This is the inner interpreter that uses the interpretive pointer IF' to execute compiled 
FORTH definitions. It is not directly executed but is the return point for all code 
procedures, It acts by fetching the address pointed by IP, storing this value in register 
Hi It then jumps to the address pointed to by the address pointed to by H, H points to 
the code field of a definition, which contains the address of the code which executes for 
that definition, This usage of indirect threaded code is a major contributor to the 
power, portability, arid extensibility of FORTH, 



ccl — cc2 ASSEMBLER 
Used in ASSEHBLER conditionals, it reverses the condition code for the conditional that 
follows, For example*, CS NOT UNTIL, will terminate the loop if the carry is not set, 

— addr (assembling) ASSEMBLER 
n — run-time 

A constant which leaves (during assembly) the machine address of a routine which at 
run-tine will pop a 16-bit value from the computation stack arid return control to NEXT, 



— addr (assembling) ASSEMBLER 
nl, n2 — (run-time) 

A constant which leaves (during assembly) the machine address of a routine which at 
run-time will pop two 16-bit values from the computation stack arid return control to ICXT 
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PUSH — 3ddr (assembling) ASSEMBLER 

— n (run-time) 

A constant which leaves (during assembly) the Machine address of a routine which at 
run-time will add the accumulator (as high byte) and the bottom of the machine stack (as 
low byte) to the computation stack* It returns control to NEXT* 

PUT — addr (assembling) ASSEMBLER 

nl — ri2 (rurrtime) 

A constant which leaves (during assembly) the machine address of a routine which at 
run-tine will write the accumulator (as high byte) and the bottom machine stack byte (as 
low byte) over the existing top of the computation stack (16-bit value nlh 

Rp) — n (assembly-time) ASSEMBLER 

Used in code definitions in the form: 

RP) LDA* or RP) 3 + STA* 
Addresses the bottom* low order byte of the return stack by selecting the *X mode and 
leaving n=$101 or maybe modified to another byte offset* Before operating on the return 
stack the x register must be saved in XSAVE and TS<* executed* and the x register mist be 
restored before returning to NEXT* 



SEC — n ASSEMBLER 

Identical to EOT except that n=2* Addresses the low byte of the second 16-bit parameter 
stack value, the third byte on the parameter stack* 



SETUP — ASSEMBLER 

A subroutine which moves stack values to the N area* In this subroutine the accumulator 
specifies the quantity of 16-bit stack values to be moved (1-4) ♦ For example 4 * 
3 *LDA* SETUP JSR* 

takes the first three pairs of bytes from the stack and moves them to N* 



Stack before N after Stack after 

H H high byte 

G BOT G low byte 

F F 

E E 

D D 

C C 

B high byte B 

EOT A low byte A 



THEN, — ASSEMBLER 

A caviling version of ENOIF,. 





UNTIL, 



— (run-tine) ASSEMBLER 
addr, 1, cc — .(assembling) 
A word in CODE definitions that is the terminator of loops, used in the form: 

BEGIN, ♦ ** cc UNTIL, 

At rurrtime UNTIL, controls the conditional branching back to BEGIN, ♦ If the specific 
status bit specified by cc is false execution returns to BEGIN,, if true it continues 
ahead* 

At assembly time UNTIL, assembles a conditional relative branch to addr based on the 
condition code cc* The number 1 is used for error checking. 



UP 



— addr (assembling) ASSEMBLER 
A constant that returns the address of the pointer to the base of the user area* It is 
used in CODE definitions in the form* 
UP LDA, or UP )Y STA, , 



UPMODE 



addr f — addr f ) ASSEMBLER 
Used within the assembler to adjust the addressing mode based on operand size and op-code 

type* 



MS 




— cc ASSEMBLER 
Specifies that the following conditional generate a branch if the overflow bit of the 
status register is set* 



— addr (assembling) ASSEMBLER 
A constant that returns the address of the pointer to the code field (execution address) 
of the FORTH dictionary word being executed* It is used in CODE definitions in the form: 

W 1+ STA, or H 1- JMP, or H )Y ADC, 
Indexing relative to M can yield any byte in the definition's parameter field. For 
example 2 * LDY, H )Y LDA, loads the first byte of the parameter into the accumulator* 



X) 



— ASSEMBLER 
Specifies indirect indexed with x addressing mode for the next op-code generated* 



XSAVE 



— addr (assembling) ASSEMBLER 
Used in code definitions in the form! 

XSAVE STX, or XSAVE LDX, 
A constant which leaves the address of a temporary buffer for saving the x register at 
assembly time* Since the x register indexes to the data stack in zero-page, it must be 
saved and restored when used for other purposes* 



iii + i wtobj: write bootable object 

HTOBJ is a way to create bootable object disks* When the screens containing the HTOBJ words are 
loaded* the FENCE is reset to the top of the dictionary as it was just before the screens were 
loaded. Short instructions for using FORHAT and HTOBJ are printed out* To create an object code 
boot disk* you should FORHAT it (if it isn't formatted already) * then put the disk, in drive *1 and 
type HTOBJ ♦ HTOBJ will write a short machine code routine (pointed to by BOOT) onto sector 1, 
followed (on succeeding sectors) by the contents of the dictionary up to FENCE* When this new disk 
is booted, the routine on the first sector will load in the rest of the boot* This version of HTOBJ 
will only create boot disks of 255 sectors or less* 



CALLDK 



Routine for Moving a sector to or from disk.* Assumes that the device control block has 
been set up* 



DKIO 



addr nl nZ — 

Instructs the disk, drive specified by the lower byte of n2 to perform a disk operation on 
sector nl* The upper byte of n2 determines which operation (read, write, format, etc*) is 
performed* addr is the address of the 128 byte buffer used for this operation* 



HTSEC 



addr n — 

Hrites 128 bytes, starting at addr, to sector n of drive *1* 



RDSEC 



addr n — 

Reads 128 bytes from sector n of drive tl to memory, starting at addr* 



FORMAT 



n 



Formats the disk in drive n* First asks whether the user really wants to format, just in 



case* 



BOOT 



— addr 

Points to the starting address in memory of the code routine that is put onto the first 
sector of a bootable object code disk (by HTOBJ) ♦ Hhen this disk is booted later, this 
routine loads in the rest of the object code that was put onto the disk by HTOBJ* 



HTOBJ 



Creates a bootable object disk out of the FORMATted disk in drive *1« First puts the code 
routine that BOOT points to onto sector 1, then writes the contents of the dictionary (up 
to FENCE) to the disk* FENCE was reset to the top of the dictionary when the HTOBJ 
screens were loaded. Hhen this new disk, is booted, the code in the first sector will load 
in the rest of the boot* 




Coin-Op FORTH provides a set of disk copying routines in source code which can he loaded on top 
of the boot i The nost important of these are CLONE » OBJ i and COPYDISK • For each of these, the 
source disk should he inserted in drive 1, and the destination disk in drive h More of then has any 
effect on the stack* Executing CLONE will copy the entire source disk.* OBJ copies only the original 
Coin-Op boot screens (probably screens $ - B to -1, unless PHYSOFF or OFFSET have been changed by the 
user)* If extra boot screens are added OBJ will not copy them* COPYDISK will copy the entire disk 
except for the Coin-Op FORTH boot screens* 





111*3 Line Printer WoircJ -ee> 

CoirrOp FORTH provides a set of words for printing disk screens on the line printer • Although 
written for use with the Atari 822 printer, one snail Modification will Make then suitable for use on 
an Atari 825 or an equivalent printer (such as the Centronics 739) ■ This Modification is as follows! 
on the second line of the first screen of source code for the printer words, the definition 

3A50 VARIABLE P! 
should be changed to 

3250 VARIABLE Pi 3A , 

This places the ATASCII characters P2t , rather than P! , into the parameter field of this variable* 
This change only needs to be Made if you are not using an Atari 822 printer* 

The printer should be turned on (as should any interface Module used to connect the printer to 
the Atari) and switched to ON-LINE when the printing words are loaded, or else the printer will not 
be "opened". The comand LPOPEN will open the printer after a SYSTEM RESET (or if the printer was 
not on line when the printing words were loaded)* 

There are three basic line printer routines available to the user* The first is LISTLP* which 
simply takes a disk screen number off the stack and prints that screen on the line printer* SHOWLP 
takes two arguments, a final screen it, and a starting screen n, and prints screens n to m on the line 
printer* If the number of characters per line on a screen is equal to 32, the screens will be 
printed in two columns? otherwise the screens will be printed in ore column* Finally, LPINDEX takes 
the same arguments as SHOWLP, but prints only the first line of each screen* 

The Atari words also allow the use of two different styles of print* After SHRBK is executed, 
files will be printed in condensed print* EXPAND returns the print size to normal* 



♦CLP n — 

Takes a number n from the stack and prints it at the line printer* If r» is a single-digit 

number, it will print a preceding 0* 



•LP n — 

Takes a number n from the stack and prints it on the line printer* 



CF1P 



CRLP checks LPCNT, and if the bottom of the page has been reached (if the number in LPCNT 
is greater than $30) performs four carriage returns on the line printer to get to the next 
page* 



EXPAND 



After EXPAND is executed, files printed on the line printer will be printed with normal 
width characters* 



(Form feed*) FFLP performs successive carriage returns on the line printer until the top 



LISTLP 
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of the next page has been reached 



UMELP n — 

FT i nts line n of the host recently referenced disk screen on the line printer* 



n 



Prints screen n with line numbers on the line printer* 



LPCNT 



— addr 

A variable which holds the number of carriage returns the printer has performed on a page* 



LPCR 



Performs a carriage return on the line printer and increments LPCNT 



LPEMIT 



n — 



Takes one ATASCII character from the stack and prints it on the line printer* 



LPINDEX n, m — 

Prints line 0 of screens n through m on the line printer* 



LPOPEN 



OPENs a line printer device/file* This must be called before using any printer words* 



LPSPC 



n — 

Prints n spaces on the line printer* 



LYP1 



addr* m — 

Sets the beginning of the line printer I/O buffer to addr with length n bytes, and prints 
the contents of the buffer • 



LYPE 



addr* n — 

Prints m bytes of the buffer starting at addr on the line printer, followed by a 
If the buffer is longer than one line (80 characters) it increments LPCNT* 



pi 



— addr 

A variable which contains the ATASCII equivalent of the characters Pi, if an Atari 822 
printer is being used, or P25 if an Atari 825 or equivalent printer is being used* 
PI is used as a buffer in opening the printer device/file. 



- n 



Used after parameters are set for line printer I/O* PCIO sets up 
CIO entry point ($E456h The I/O status is left on the stack* 



> #7 and jumps to the 
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PERR? 



n 



Takes the I/O status n fro* the stack and checks for error* If an error is found, PERR? 
executes ERROR* 



SCR* 



— addr 

A variable which holds the ATASCII equivalent of the characters SCR ** 



SHOHLP n f m — 

Prints screens n through n on the line printer* If the number of characters per line on 

the screens is equal to 32, the screens will he printed in two columns on the page* 

Otherwise the screens are printed in ore column* 



SHRINK 



After SHRINK is exerted, files printed on the line printer will he printed in condensed 
print* 
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These words are useful when you have to decipher compressed FORTH source code (you should rarely 
have to write such code yourself, since disk, space is not expensive)* The words allow you to list or 
print screens in a formatted fashion - they cone out looking the way they should have in the first 



The line printer words Must be loaded before the formatted print words* 

The wain words are** 

FLST a fornatted equivalent of LIST 

FLSTLP LISTLP 

FSHW SHOW 

FSHWLF — _ — — — SHOKlP 



Each first lists or prints the screen in normal fashion, then in formatted form, 



FSHHLP « n — 

For screens n through n, first prints then prints a formatted version* 



FSHW m n — 

For screens m through n, first lists, then lists a formatted version on the TV screen. 



FLSTLP 



FLST 



n 



Lists screen n on the printer, then prints the formatted version of the screen* 



n 



Lists screen n on TV screen* then lists formatted version* 
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Causes the next word in the input stream to be interpreted as a hexadecimal number . At 
compile-time, the number is compiled into the next available dictionary space} at 
run-time, the number is left on the stack* 



Causes the next word in the input stream to be interpreted as a decimal number • At 
compile-time, the number is compiled into the next available dictionary space; at 
run-time, the number is left on the stack* 



2DR0P n m — 

Drops the two top elements of the stack* 

2DUP ri m — n m n m 

Duplicates the top two elements of the stack* 

ftTftSCII>IHTEim B — i 

Code routine which takes the ATASCII value of a given character and returns the 

corresponding Internal value* 

COLCRS — addr 

A constant which returns the address that controls the full text screen text cursor's 
horizontal position (the split screen text cursor's horizontal position is controlled by 
TXTCOD* 

INTERHAL>ATASCn i — a 

Takes the Internal value of a character and converts it to the ATASCII value* 

HAP — addr 

Returns the address of the first entry in a table used in the conversion of characters 
from ATASCII to Internal representation, and vice versa* 

MOVE addrl addr 2 n — 

A "smart" form of CM0VE which moves bytes without danger of incorrect overwriting* Takes 
n bytes starting at addrl and moves them to the n bytes starting at addr2* Written in 
machine code* 

PICK xn ♦ . ♦ x3 x2 xl n — xn xl x2 x3 * * . xn 

Takes the nth value from the stack, duplicates it, and puts it on top of the stack (a 
generalized form of OVER)* 

ROLL xn * * * x3 x2 xl n — xn xl x2 x3 * * * 

Pulls out the nth value on the stack, xn, and puts it on top of the stack* The values 
which were above xn are pushed down one position to fill its place (a generalized ROT)* 

RCBCRS — addr 

A constant which returns the address that controls the full text screen text cursor's 
vertical position (the split screen text cursor's vertical position is controlled by 
I) i 
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SWMSC 



— addr 

A constant which contains the starting address of the graphics screen data. 



SETBV 



— addr 

A constant which returns the address of the vector into the OS routine SETVBV} this 
used to set titters and all new routines to VBLfiNK. See the OS Manual for details* 



is 



TXTCOL 



— addr 

A constant which returns the address that controls the split screen text cursor's 
horizontal position* 



TXTOSC 



TXTROW 



WBLKD 



WELKI 



— addr 
A constant which 



contains the address of the beginning of the text screen data, 



— addr 

A constant which returns the address that controls the split screen text cursor's vertical 
position* 

— addr 

A constant which returns the address of the deferred vertical blank vector* 



- 



— addr 

A constant which returns the address of the iwediate vertical blank vector* 






Use this exactly the same 35 regular INDEX* It is Much faster since it looks at only the sector 
Containing the top line of a screen, rather than reading in the whole screen* We have it compiled 
into our noma! boot* 




This word requires $ from the Miscellaneous Words* 
Programed by Charles A* Clinton 




INDEX m n — 

Writes the top lines of screens k to n on the TV screen* 




Supporting words on the source screen! 

DISKIO , INDE<_0NE_SECT0R , INDEX.ONE.SCREEN 




The CASE structure is a powerful branching system which offers an easy-to-use and 
maintain alternative to nested IF.*.THENs* The basic CASE structure is as follows 
n CASE 

ml OF xxxl FO 
«2 OF >oo«2 FO 
♦ 
♦ 
♦ 

my OF xxxy FO 
OTHERWISE OF mo FO 
ESAC 



At execution, the entry value n is compared with ml, m2, ♦♦* my* If n is equal to some mi, the 
string of words mi is executed, and execution exits the CASE structure* If n is not equal to any 
of nli tfZj *♦« mil the OTHERWISE conditio, xxxO, will be executed, and execution will leave the 
structure (if no OTHERWISE condition is included, ESAC will clean up the stacks, and execution 
continue to the next word in the definition). An important thing to note is that ml, m2, ♦ ♦♦ ny can 
be either literals or set of words, provided they leave a number on the stack to be compared with n 
by OF. 



EXAMPLE** 

Suppose you need a program called MSHS that will keep track of the number of different colored 
n&ns in a bag as you eat then *e*g* 

3 brown mm 

will increment the variable BROWN by 3* This can be done using CASE as follows: 
0 VARIABLE BROWN 
0 VARIABLE YELLOW 
0 VARIAEtE ORANGE 
0 VARIABLE GREEN 



mm (n, addr — 

BROWN OF BROWN +! FO 
YELLOW OF YELLOW + ! FO 
ORANGE OF ORANGE + ! FO 
GREEN OF GREEN +! FO 
ESAC : 



) 



CASE 



When, for example, the line* 
2 GREEN HSHS 

is executed, the number 2 and the address of the variable GREEN are left on the stack* This address 
is first compared with the address of the variable BROWN, then that of YELLOW and ORANGE, and finally 
GREEN* Since the address of GREEN left on the stack outside the CASE structure will equal the 
address of GREEN left on the stack inside the CASE structure, the string GREEN +! will be executed, 

of GREEN will be incremented by two* 



This can be a very useful program, since it is important not to eat too many green m&ms (they 
make you sterile). 
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$CASE 



$F0 




Run-tine procedure conpiled by CASE which places the following in-line paraneter on the 
return stack* This parameter is the address later used by $F0 to exit fron the CASE 
structure* 



The run-tine procedure compiled by FO which causes execution to exit fro* the CASE 

structure i 



$0F n n — (if n%)i or 

n n — n (if n On) 

The run-tine procedure compiled by OF* This compares two values on the stack, and if they 
are equal, executes the words following $0F* Otherwise it leaves n on the stack and 
execution continues after the next $F0. 

CASE run- tine 4 * — 

conpile-tine* — addr 
Used in the forn* 
n CASE 

ml OF xxxl FO 
h2 OF xxx2 FO 



ny OF xxxy FO 
OTHERWISE OF xxxo FO 
ESAC 

CASE opens the CASE branching structure which compares n to ni, h2 t etc* If n is equal to 
ni, then the string of words xxxi will be executed and FO will cause execution to exit the 
CASE structure Any t\i nay be a literal or a string of words which leave a value on the 
stack to be conpared with n* If none of nl,*** ny are equal to n, the OTHERWISE string, 
xxxo, will be executed* Then execution continues after ESAC* 

At conpile-tine, CASE compiles the run-tine word $CASE, and reserves space at addr for use 
by ESAC* 

ESAC run-tine* n — 

conpile-tine J addr — 

Used at the end of a CASE structure. At run-tine, ESAC cleans up the return arid paraneter 
stacks if no natch for the entry argunent was nade inside the CASE structure (if a natch 
. was nade, FO would have caused execution to exit the structure, and ESAC would not be 

executed), 

At conpile-tine, ESAC conpiles R> and 2 DROPS to clean up the stacks, and stores the next 
available dictionary position into addr, which was left on the stack by CASE* 
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FO 



run-tine** — 

conpile-tine** addr — 

At run-tine, FO causes execution to exit fron the CASE structure if a watch for the entry 
argument has been nade* (See CASE*) 

At conpile-tine, FO compiles the run-tine word *F0 and stores the address of the next 
available dictionary position into addr, which was left on the stack by OF* 



OF 



run-tine* n rt — (if n=n) 
ori n n — n (if nOn) 
conpile-tine** — addr 

At run-tine, OF compares two values on the stack (n was left on the stack before the CASE 
structure was entered; ft was left on the stack inside the CASE structure)* If these 
values are equal, the string of words* xxx will be executed* and the following FO will 
send execution out of the CASE structure* If the values are not equal, OF leaves h on the 
stack-., and execution continues after the following F0*(See CASE*) 

At conpile-tine, OF compiles the run-tine word $0F, and reserves space at addr for use by 
FO* 



OTHERWISE 




n — n n 

Used in the CASE structure in the forn** 
OTHERWISE OF xxx FO 

OTHERWISE will cause the string of words xxx to be executed* OF is expecting to conpare 
two values on the stack and execute xxx if they are equal*, OTHERWISE sinply duplicates the 
value on the stack* 



IV + 4 LIST ASSEMBLER WORDS 

These words allow the user to create ANTIC display lists in the FORTH dictionary* Read De Re 
ATARI chapter 2 (ANTIC and the Display List) before using these words* 

These words have four advantages* First, because they employ Mnemonics, creation and 
Maintenance of display lists becomes Much easier than would be the case if the user had to deal 
directly with the numerical ANTIC cowhands* This is roughly analogous to the difference between 
writing Machine code via an assembler and writing it "by hand" - number by nuMber* (Of course * in 
the case of both Machine code and display lists, the user should have at least soMe understanding of 
the underlying nuMerical coMMands*) 

The second advantage lies in the convenience of placing display lists in the FORTH dictionary, 
where they are created at conpile tine and can be easily accessed* This saves the user froM the 
hassles of Moving custoM-huilt display lists in fro* disk or building then at run-tine t and it avoids 
the probleMS of finding space for a display list between player/Missile MeMory and display MeMory* 

The words are quite easy to use* Bear in Mind that, like FORTH assembler Mnemonics, they 
operate in execution rather than cohpile Mode* (This Means that they can be placed inside other 
FORTH words to create "Macros"*) 

A dictionary based display list starts with the coMMand J DUST , followed by the user's nane for 
that diplay list" (let us use the nane DL*EX)* iDUST will create a FORTH header for DL*EX* 
Subsequent execution of DL*EX will leave its PFA on the stack 1 , this in turn is the first byte of the 
new display list* 

After the header, the diplay list is created* This is done through the use of the following 
four coMMands* (All of these coMMands have a , (coMMa) as the last character of their nane? this 
indicates that they store a value onto the dictionary*) 

JMP, - This coMMand causes display list execution to ".Jump" to a new address (other than the 
next byte in MeMory), where the display list will continue* It has the effect of leaving one blank 
scan line on the display screen, and it is rarely used* JHP, is used in the for-M* 
addr JHP, 

where addr is the address to which the display list will Jump* 

BLANK , - This is used in the forM? 
n BLANK, 

This coMMand places between 1 and 7 blank scan lines on the screen* n indicates how Many blank lines 
are desired* It is always used at the beginning of display lists (see De Re Atari), but it car. be 
used anywhere the user desires* 

MODE, - This is used to set up graphics Mode lines* It is used in the forM* 
[address (of LMSV3 [options] [Mode #3 HODE, 
This creates an ANTIC instruction indicating one Mode line of graphics Mode [Modetl* It May also 
indicate one or More of these four options - LHS (load MeMory scan), VSCROLL (vertical scrolling 
enabled), HSCROLL (horizontal scrolling enabled), or DLI (display list interrupt)* The option or 
options should be indicated before the Mode line *♦ Finally, if one of the options is an LHS, the 
word LHS should be preceeded by the LHS address (i*e*, the address of the start of display da J * 
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For example j 

$ BOOO LMS VSCROLL 2 MODE, 
will create en ANTIC Mode 2 (graphics 0) Mode line, with vertical scrolling enabled and an LMS which 
indicates display MeMory starts at i B000» Another exanplet 

6 MODE, 

creates an ANTIC Mode 6 (graphics 1) line* 

The word OF-THEM is used to indicate that not one but several node lines identical to the one 
Most recently created should be placed in the display list* Thus, the connandt 

VSCROLL 7 MODE, 10 OF-THEM, 
will coMpile 10 Mode 7 (graphics Mode 2) lines with vertical scrolling enabled 4 , this avoids the 
necessity of repeating coMplicated (or even uncoMplicated) instructions a nuMher of tines* OF-THEM, 
can also be used with BLANK,* 

JVB, ♦ This is used in the forM** 
Caddrl JVB, 

arid indicates that the screen is conpleted, and as such display list execution should Jump to Caddrl 
and wait for vertical blank to occur* CaddrD will alMost always be the address of the first byte of 
the display list; this address can be obtained by executing the nane of the display list! 
DL*EX JVB, 

will thus cause display list execution to Jump to the top of display list DL*EX* 

A dictionary-based display list ends with the FORTH word DL*, * This word checks to see if the 
display list crosses a IK boundary (which is not allowed)* If it does, a Message to this effect is 
issued to the user, who Must then either rearrange the source code or allot eMpty space in the 
dictionary so that the display list does not cross the boundary* 

NOTE** There is one real disadvanege (other than the boundary probleM just Mentioned) with 
dictionary based display lists* Because they are created at coMpile tine and used directly, it can 
be very difficult to "clean up" a display list after it has been altered in soMe way (for exaMple, 
scrolling will change the LMS addresses)* It May be necessary to store LMS addresses and the like in 
separate constants and to have a word which uses these constants to recreate the "original" display 
list* 

After the display list is created, execution of its nane will return its starting address* This 
address can then be stored into S-DUSTL ($230) in order to activate the display list. 

Here are 2 exaMples of display lists (in deciMal fori*)* 

JDLIST DL*EX1 
7 BLANK, 
3 OF-THEM 
$ BC60 LMS 2 MODE, 
2 MODE, 23 OF-THEM, 
DL.EX.l JVB, 

DLJ 

(This creates a normal graphics Mode 0 screen of 24 lines, the first of which has an LMS*) 
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!DUST DL*EX2 

7 BLANK, 3 OF-THEH, 

$ BOOO LMS VSCRDLL 7 MODE, 

VSCROLL 7 MODE, 9 OF-THEH, 

DLI 7 MODE, 

$ Ef60 LHS 2 MODE, 

2 MODE, 3 OF-THEM , 

DL*EX2 JVBi 

DL? 

(This creates 3 10-line scrolling graphics hode 2 screen with 3 four line graphics mode 0 text 
window! there is a DLI just efore the text window* See Se Re Atari chapter 6 for an explanation of 
why there are 11, rather than 10, ANTIC node 7 instructions*) 

The Display List Assembler words were programmed by Charles A* Clinton* 



♦DUST 



Used in the form* 

J DUST xxxx Mt-DL! 

4 *DLIST creates a dictionary entry for xxxx and sets MASK to 0, thus setting up the 
conditions for compiling a display list into the dictionary* ANTIC instructions can then 
be stored into xxxx's parameter field by using the display list assembler instructions*, 
compilation of the display list is terminated by DL*,* When xxxx is executed, it leaves 
its PFA on the stack*, this is the address of the first byte of the display list, which can 
then be used to instruct ANTIC to use display list xxxx* At compile-time J DUST leaves 
addr (xxxx's PFA) on the stack, for subsequent error checking by DL}* 



BLANK, 



n 



Compiles an ANTIC instruction in the dictionary* The instruction calls for n blank scan 
lines, where n - 1 ■• -to 7* 



dl; 



addr — 

Finishes compiling a display list by ensuring that the display list has not crossed a IK 
boundary; if it has, a message to this effect is issued to the terminal, and 
interpretation of the input stream continues normally* addr is the address of the first 
ANTIC instruction in the display list, which is left on the stack by JOUST* 



DU 



Adds $80 to the display list instruction currently being created (contained in MASK)* 
This indicates that a display list interrupt will occur on the mode line corresponding to 
the instruction* 



BSCROLL 



Adds $10 to the ANTIC instruction currently being created* This indicates that horizontal 
scrolling is enabled on the mode line corresponding to the instruction* 
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addr — 

Compiles an ANTIC JHP instruction, along with the address with which to reload the display 
list counter, into the dictionary. This instruction will leave one blank, scan line on the 
screen* 



addr — 

Compiles an ANTIC "Jump and wait for vertical blank to end" instruction, along with the 
address with which to to reload the display counter* This address is usually the starting 
address of the display list. 



LHS 



Adds $40 to the ANTIC instruction currently being created. This indicates that a "load 
memory scan" should occur on the mode line corresponding to the instruction* 



MASK 



— addr 

A variable used to hold display list instructions temporarily as they are being created. 



MODE, 




addr, n — (LHS) 
n — (non-IMS) 

Compiles an ANTIC instruction into the dictionary. The instruction indicates one node 
line of ANTIC node n, along with any other conditions (LHS, vertical arid/or horizontal 
scrolling, DLI) preset in MASK. If the mode line contains an LHS, the new display data 
address is compiled immediately following the ANTIC instruction* MASK is reset to zero. 



OF-THEMj 



n 



Follows BLANK* or MODE,. Compiles ml ANTIC instructions, identical to the last one 
compiled before entry into OF-THEM, into the dictionary (e.g., 2 MODE, 23 0F-T}£M will 
compile a total of 23 ANTIC mode 2 lines). 



Sets MASK to 0, in preparation for the creation of the next ANTIC instruction. 



VSCROLL 



Adds $20 to the ANTIC instruction currently being created (contained in MASK). This 
indicates that vertical scrolling will be enabled on the mode line corresponding to the 

instruction* 





The word on the source screen is actually a tenplate. To use just change the 8 x 8 natrix of O's 
and 1's to for* the character desired arid renane the resulting word* Replace "beginning addr." by 
the beginning address of your character set (see the discussion below) . To replace a character by 
your character, find its Internal number n in the Internal Character Set (Table 9*6 of the Basic 
Reference Manual) , and do n <your na*e for word>. For example 0 ARROH-HEAD would replace "space" by 
the arrowhead ♦ 

This routine requires * fro* the Miscellaneous Words ♦ 



Character set manipulation} 

The highest two hexadecimal digits of the address of the beginning of the character set 
currently being used are stored in the variable CHBAS (normal value $EQ) , the other two digits of the 
address are 00. 

To change the normal character set, select a memory address beg.addr, which lies on a IK 
boundary (i.e. its last 2 digits must be 00), arid for which you can afford to dedicate the following 
1024 bytes to character set storage. Then CHQVE $400 bytes fro* $E000 to beg.addr. This gives you a 
changeable character set ($E000 to *E4Q0 is in ROM). Change characters as described above. To make 
your new character set the current one, take the highest two digits of beg .char and do CHBAS C! 
After having modified a character set, you nay wish to store it on disk. 




IV.6 



To find all appearances of a string xxxx on screens scrl through scr2 inclusively* type: 



scrl scr2 SEARCH xxxx 

The computer will print out each line that contains the string, along with the line nurter and the 
screen nuftber* 

SEARCH will recognize leading, but not trailing blanks* Thus, letting T denote blank, 
n r. SEARCHbFF 
would picks up both "BUFFER" and "$ FF" but 



ft n SEARObbFF 
would only pick, up "$ FF M » 



Supporting words on the source screens *♦ 

♦LOCATE, *LEAD, *LAG, INFORM, TOP MATCH, 1LINE, FDO, COUNTER, BUT. 

Programed by Jay Scott ♦ 




( 
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MODES 



The graphics printing words work exactly like the normal FORTH text printing words, except that 
they print characters in graphics Modes* For each of three graphics nodes (nodes 1, 2 and 7), there 
are words that correspond to BUT* TYPE, arid , and words that position the cursor for printing* 
There are also counterparts to EMIT, TYPE, and • " for the text window (the parameters that position 
the cursor in the text window are given directly to T H ). Since graphics characters are represented 
in nenory in INTERNAL rather than ATASCH forn, there are words that do what * , #S , HOLD , SIGN , 
and WORD do, except that they create a string in INTERNAL forn instead of AT ASCII* These words are 
used to format pictured numeric output* TOJXTERNAL will convert a string fron ATASCIE to INTERNAL 
representation. Other useful words in the graphics printing set include 7REMERSE, a variable which 
deternines whether node 7 characters should he printed in nornal or inverse video forn; and 
D_Etf;-TEXT4CDIMW, which clears a portion of the ted window* 

Internally, the graphics printing words use SAUMSC and TXTHSC, which tell where the first bytes 
of graphics arid text nenory are, respectively* The node 7 words use XPA!€&CQL0R, which tak.es an 
8-bit slice of a character in the character set and widens it to 16 bits for printing in the higher 
resolution node 7* (Mode 7 characters look, exactly like node 2 characters*) 

These words require * fron the Miscellaneous Words* 

The graphics printing words were programed by Chris Helck* 




#-I dl — d2 

Fron a double number dl, generates the next character (in Internal, not ATASCH, 
representation) which is placed in the pictured-nuneric output strean* The double nunber 
d2 is the quotient after dl is divided by BASE and is naintained for further processing* 
(Direct conterpart to #♦) Use only between <* and *>* 

*S-I dl — d2 

Converts all digits of the double nunber dl to pictured nuneric representation, adding 
each digit to the output text} the resulting text is in Internal, rather than AT ASCII, 
representation* The double nunber d2 is the renaining quotient, arid is always zero* 
(This is a direct counterpart to *S*) Use only between <* arid *>* 

<1") — 

Run tine code for 1" and 2'\ Prints the following in-line string (in Internal 
representation), with a count in the first byte, on a node 1 or 2 screen* The string's 
color will be deternined at run-tine, on the basis of what color was nost recently 
selected by the user* 

in — 

Run-tine code for 7"* Prints the following in-line text string (in Internal 
representation), with a count in the first byte, on a node 7 screen*, the string will be 
printed in the color nost recently set* 



(T") 



r 
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nl n2 — 

Execution procedure for T n * Prints the following in-line text string, 
the first byte, in the text window starting 3t column nl, row n2* 



in 



Used in the form* 

r xxxx" 

Compiles an irrline string xxxx, delimited by M (double quotes), with an execution 
procedure (1") to transmit the text to a mode 1 screen (in the color most recently set by 
a COLOR command)* If executed outside of a colon definition, i M immediately prints the 
string ♦ The string way not exceed 255 characters ♦ 



1EMTT 



lPOSmON 



1TYPE 



n 



Places the node 1 character with internal representation n on the screen, at the current 
cursor position (see 1P0SITI0N) ♦ The character will have the color most recently selected 
by the user* The cursor position is updated by 1 character* 



x y — 
Sets the current cursor postion to 
will be placed at this spot* 



x, y on a mode 1 screen 4 , the next character printed 



addr c — 

Places the string beginning at addr, with character count c, on a mode 1 screen starting 
at the cursor position (see 1P0SITI0N) . The string will have the color most recently 
selected by the user* The string must already be in Internal representation* 



2EMIT 



Used in the form* 

r xxxx n 

Compiles an in-line string xxxx, delimited by " (double quotes), along with the execution 
procedure (l ,f ) which transmits the text to a node 2 screen (in the color most recently 
set)* If executed outside of a colon definition, 2" immediately prints the string* The 
string may not exceed 255 characters* 

n — 

Places the mode 2 character with Internal representation n on the screen, at the current 
cursor position (see 2P0SITI0N)* The character will be printed in the color most recently 
selected by the user* The cursor position is updated by 1 character* 



2P0SITI0N 



2TYPE 



x y — 

Sets the DJrrent cursor position to x, y on a mode 2 screen} the next character printed 
will be placed at this spot* 

addr n — 

Puts the string beginning at addr, with character count n, on a mode 2 screen starting at 
the cursor position (see 2P0SITIQN)* The string must already be in Internal 
represenation, arid it will have the color most recently selected by the user* 



Print in<3 Words , p*3 



7" 



Used in the for*: 



m XXXX" 



Compiles an in-line text string, delimited by M (double quotes) , along with the execution 
procedure (7 M ) which, when executed, transits the text to a mfe 7 screen. The 
characters have the appearance of node 2 characters} the full range of ATASCII characters 
is available to the user* The string will be in the color nost recently set* If executed 
outside of a definition, 7" causes the string xxxx to be printed iwtediately. 



7EKET 



n 



Prints the character with Internal representation n on a node 7 screen* The character 
will be in the color host recently selected by the user, and its upper-left corner will be 
at the graphics cursor* The cursor will be updated by 8 pixels. The character will have 
the appearance of a node 2 character* 



7P0S3TI0N 



x 



Sets the graphics cursor to x, y on a node 7 screen*, the next *ode 7 character printed 
will have its upper-left corner at this spot. Horizontally, characters Must start on byte 
boundaries (every four pixels)} vertically characters nay start on any scan line. 



7REL*SCRN! 



nl n2 — 

Stores the 16-bit value nl into the address which is rtZ bytes after the start of screen 
nertory* 



7REVERSE 



— addr 

A variable which holds an indicator as to whether node 7 characters should be printed 
nornally or in inverse video* Contents=0 indicates normal, contents O 0 indicates 
inverse. 



addr n — 

Places the text string beginning at addr, with character count n, on a node 7 screen, 
starting at the graphics cursor (see 7P0SITI0N). The string will have the color rest 
recently selected by the user} the characters will have the appearance of «ode 2 
characters. The string mist already be in Internal representation. 



CLEAR-TEXT-ODOW n — 

Clears the first n lines of the text window, 
text window is stored in TXTMSC. 



Assunes that the starting address of the 



HOLD-I 



Inserts the character whose Internal representation is c into the pictured numeric output 
string. For exanple, $E HQLD-I will place a decimal point into the next spot of the 
output text* (Direct counterpart of HOLD*) Use only between <* and #>* 



REL-SCRN! c n — 

Stores the 8-bit value c into the nth byte after the start of screen Kenory* 



SIGK-I 



n d — d 

Inserts the Internal value corresponding to (Minus sign) into the pictured nu*eric 
output string (if n is negative)* (Direct counterpart to SIGN*) Use only between <* and 
*>* 
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T" 



— (conpiling) 
nl ri2 — (execution) 
Used in the torn* 

nl nZ T" xxxx"* 

Cohpiles the irrline text string xxxx, delinited by " (double quotes), along with the 
execution procedure (T")» Iflien executed, the string will be placed in the text window at 
colum rdi row r»2* If executed outside of a definition, T n prints the string immediately* 



TEMTF 



n 



Puts the character with ATASCII value n in the text window at the current cursor position, 

position by 1 character* 



TO. INTERNAL addr — 

Converts the string beginning at addr, with a count stored in the first byte, fron ATASCII 

to Internal representation* 



addr c — 

Prints the ATASCII string starting at addr, with count c, in the text 
the current ojrsor posit ion* 



at 




WOFft-I c — 

Reads the input strean until a deliniter c is encountered, Moving the text to HERE (with 
the character count in the first byte), and converts the ted troa ATASCII to Internal 
representation* (Direct counterpart to WORD*) 

XPAtfttCQLQR nl — n2 

Expands an 8-bit value nl (obtained fron the character set) to a 16-bit value rtZ for use 
on a node 7 screen* Hhen placed on a node 7 screen, the bit pattern will reproduce 1 scan 
line of a character in the color currently selected by the user. This allows characters 
to be printed in node 7 using the character set. (Each bit of nl naps to two bits of n2} 
bit x of nl naps to bits 2x and 2x+l of n2*, a 0 naps as 00, while a 1 naps as 00, 01, 10, 
or 11, depending on the current color.) If 7REVERSE is non-zero* the ones conplenent of 
ri2 is returned* allowing the printing of "stencil" characters. 



Non-boot words used*. ATASCIDINTERNAL, INTERNALS ASCII, HAP. 





The word CCOPY copies consecutive screens fro* sone given range to screens starting at a new 
beginning nw*er. It's a smart copy routine, i*e* the new and old screens can overlap ♦ 

CCOPY Clstl Bast] Cnew 1st] — 

Copies screens Cist] to Clast] to screens starting with Cnew 1st] 



MCOPY wakes Multiple copies of a screen over so*e interval* 



HCOPY Cist] Clast] Cscr, to be copied] — 

rtak.es copies of Cscr, to be copied] over the screens in the interval 
frcm screen Cist] to screen 





IV*9 VERTICAL SCROLLING 



Read chapter 6 (Scrolling) of De Re Atari for a discussion of scrolling on the Atari ♦ 

These words were created for use with Atari text nodes. The following procedure explains how to use 
then* 

W Load the vertical scrolling words* $ nust first be loaded fro* the Hiscellaneous Words* 

2*. Create a display list, a portion of which has vertical scrolling enabled} this section should 
begin with an LHS connand and it should not have nore than one LHS* The section should include one 
nore node line than you wish to appear on the screen, and the very last display instruction in the 

scrolling section should not have vertical scrolling enabled* (Thus, if 10 node lines of scrolling 
graphics node 2 are desired, 11 erode 2 instructions should be placed in the display list, but only 
the first 10 should have vertical scrolling enabled* See De Re Atari*) 

Set up the scrolling variables* These aret 
U5QRDLL4J6 

Store the address of the nenory location in the display list which iiwediately follows the scrolling 
section's LHS (i*e*, the address of the LHS address, which is the address of the start of the 
scrolling display data) into this variable* 

SCAN*LBES/U>E 

This variable should be set to the value which is one less than the number of scan lines per node 
line in the graphics node being scrolled* (Graphics node 2 (ANTIC 7) has 16 scan lines/node lire, so 
the proper value for it is 15 ($F)5 graphics nodes 0 and 1 (ANTIC nodes 2 and 6) have 8 scan/lines 
per line} the value for then should be 7*) 

BYTES/LINE 

This variable should contain the nunber of diplay data bytes per node lire in the graphics section* 
This value is 20 ($11) for nodes 1 and 2 (ANTIC nodes 6 and 7), and 10 ($28) for node 0 (ANTIC node 

4*_ Clear the scrolling registers by executing the word CLEAR* SCROLL* REGS * 

At this point, scrolling should be enabled arid ready to go* Execution of the word IP will scroll the 
text ore scan lire up} execution of the word DOWN will scroll the text one scan lire down* 

Tining is crucial in scrolling* It nust happen regularly and it nust happen when the TV scan is 
beneath the graphics area of the screen (otherwise, the scrolling will jerk arid the screen will 
flicker)* For this reason, IF and DOWN nake sure that changes to the scrolling registers occur only 
after the TV scan is beneath the screen by perforning a delay loop*, this prevents screen flicker* It 
serves also to nake sure that scrolling occurs very regularly, as it can thus occur no faster than 
every l/60th of a second (the tine it takes to "draw" the TV screen) , and as long as there are not 
too nany routines between successive cells to UP and DOWN, it will occur no slower than every l/60th 
of a second* (We have found that quite conplicated tests can be perfoned between successive calls to 
UP and DOWN without slowing down the scrolling, so the user need not worry too nuch about this 
problem) 

The variables VSCROLL* COARSE* REG and VSCROLL* FINE* REG exist to allow checks as to how far in a given 
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direction scrolling has proceeded; the values in these registers can thus be used to stop scrolling 
at a given point. Bear in mind that both variables must be tested to see how far scrolling has 
progressed* (Mote that, in addition to these two variables, the scrolling routines also change the 
LMS address in the display list and the hardware scroll register,) 



Here is a typical scrolling routine*. 

: MERTICAL ♦ SCROLL ( — ) 
0 STICK DIP ( RETURNS STICK VALUE ) 



= ( UP ) 
IF 

IP DRW 
ELSE 
* D = ( DOWN) 
IF 

DOWN 
THEN 
THEN ; 



This checks the joystick arid scrolls up or down, depending on which direction the joystick., is 
pressed. This word could then be used in a BEGIN ♦♦, UNTIL lew, or a similar loop, along with 
various tests of the scrolling variables, to allow the user to scroll over text, up and down, using 
the joystick.. 



The Vertical Scrolling 



were 



Brock A, Miller. 



BYTES/LINE 



— addr 

A variable which contains the number of data bytes per node line in the current graphics 
mode. Must be set by the user* 



<3N 



CLEAR, SCROLL, R 

Sets the hardware arid shadow vertical scrolling registers (VSCROL, ^SCROLL 
VSCROLL, FINE, REG) to 0, Used to initialize scrolling, 



I.REG, 



C0ARSE,D0WN 



Performs a coarse scroll by decrementing the LMS address in the vertical scroll section of 
the display list (pointed to by VSCROLL,LMS), It also decrements VS^IJLL. COARSE. REG by 1 
arid sets the fine scrolling registers to their maximum values (contained in 
SCAN, LINES AJ>E) ♦ The overall effect is to move text down one scan line on the screen. 



COARSE, UP 



Performs a coarse scroll by incrementing the LMS address in the vertical scroll section of 
the display list (pointed to by MSCROLL.LMS). It also increments VSCROLL, COARSE, REG by 1 
and sets the fine scrolling registers to zero, The overall effect is to move text one 
scan line up on the screen. 



Scrolls text one pixel down in that portion of the screen which has vertical scrolling 
enabled ♦ Perf orris a fine scroll or a coarse scroll, as needed ♦ 



FTNE*D0WN 



Decrements the vertical scroll register (VSCROL) by one, causing the text on the screen to 
move one scan line down* Also decrements the shadow register (VSCROLL*FD£*REGh Waits 
until the TV scan is off -screen to change the registers, in order to avoid flicker* 



FBE*UP 



Increments the vertical scroll register (VSCROL) by one, causing the text on the screen to 
move one scan line up* Also increments the shadow register (VSCRIXL^FTNE^REG)* Haits 
until the TV scan is off -screen to change the registers, in order to avoid flicker ♦ 



CFF* SCREEN* WAIT — 

A machine code routine which loops until VCOL&fT, the TV scan line counter, indicates that 
the TV scan is below the graphics area*, this is used before scrolling words to ensure that 
scroll registers are not changed while the scan is on the screen* 

SCAN*LDCS/LM: — addr 

A variable which contains a value which is one less than the number of scan lines per mode 
line in the current graphics mode* Must be set by the user* (e*g*, for graphics modes 0 
arid 1, the value is 7} for graphics mode 2, it is 15*) 



UP 



Scrolls text one pixel up on that portion of the screen which has vertical scrolling 
enabled* Performs a fire scroll or a coarse scroll, as reeded* 



VSCROL — addr 

A constant which contains the address of the hardware vertical fine scroll register 
($CH05)* This is a ore byte, write-only register* 



VSCROLL ♦ COARSE • REG — addr 

A variable which contains the number of coarse scrolls performed relative to the starting 
point of the scrolling* 



VSCROLL* FINE. REG — addr 

A varisbie which is used to shadow the hardware vertical fine scroll register (VSCROL) , 

which is a write-only register* 



VSCROLL.LMS — addr 

A variable containing the address in memory of the LMS address which is to be changed by 
the scrolling routines (i*e* the address of the first byte of scrolling memory). 
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IV40 PLAYER — MISSILE GRAPHICS 

The words preseriied here are easier to use arid Make code nore readable arid Maintainable thari 
siMply writing to player-Missile and graphics registers* Nonetheless, the chapter in De Re ft tar i on 
player-Missile graphics should be read carefully before using these words ♦ 

The first steps in setting up player-Missile graphics are to choose an address for the beginning 
of player-Missile MeMory, choose either single- or double-line resolution* arid set the appropriate 
bits in DHACTL and GRACTL* All of this is done by SET-P&M* SET-P&M takes two arguments off the 
stack} the resolution (1 for single-line, 2 for double-line), arid the address of the start of 
player-Missile MeMory, SETJF'&M then enables the players in DMACTL and GRACTL, sets the variables 
MISSILE J, PLAYER J, etc ♦, and clears player-Missile MeMory* 

With player-fiibsile graphics set up, the next step is to get something on the screen* Since the 
Atari provides so Many special features, it way take several steps to forM any particular inage on 
the screen* The first step is to store the inage in player-Missile MeMory (see De Re Atari page 
4-3)* Setting the horizontal position of players arid Missiles can be do-* using HP0B!« HPQS! tak.es 
two arguments off the stack* The first is the player or Missile nuMber - 0 through 3 for players 0 
through 3*, 4 through 7 for Missiles 0 through 3* The second is the horizontal position, froM about $ 
50 for the left-hand side of the screen to $ 200 for the right-hand side* The widths of the players 
and Missiles are controlled by SIZE!* which also takes two argunents off the stack.* The first is 
again the player or Missile nuMber* This is 0 through 3 for players 0 through 3 respectively, but, 
unlike HPOS! , all the Missiles are controlled by 4« This is because the sizes of all the Missiles 
are controlled by one register, SIZEM, whereas each has its own horizontal position register* Bits 0 
and 1 of SIZEM control the size of Missile 0, bits 2 and 3 Missile 1, etc* The second arguwent that 
SIZE! tak.es froM the stack is the width*, 0 or 2 for single-width* 1 for double-width, or 3 for 
quadruple-width* If SIZE! is used to set the width of the Missiles, they Must all be set at once* 
For exaMplet 

$ AB 4 SIZE! 

will set Missile 0 to quadruple width, and the others to single-width* 

The priority of objects on the screen (which object will appear to be "in front" when two 
objects overlap) can be set by PRIORITY, which takes a nurtber froM 0 to 15 off the stack, and stores 
it in the first four bits of GPRIOR* There are four basic priorities: 1 PRIORITY gives all four 
players priority over the four playfield colors*, 2 PRIC&TTY gives players 0 arid 1 priority over the 
playfield colors, which then have priority over players 2 and 3*, 4 PRIORITY gives all four playfield 
colors priority over the players*, 8 PRIORITY gives playfield colors 0 and 1 priority over the 
players, which have priority over playfield colors 2 and 3 (background color is always lowest 
priority)* If priorities other than these four are used, objects with conflicting priorities will 
appear black in regions where they overlap* 

The colors of players and Missiles can be set by COLPM!* COLPM! tak.es two argunents*. the first 
is the player nutter f 0 through 3 (Missiles take the colors of their respective players)*, the second 
deterMines the color, 0 to $ FF* Fifth arid sixth player-Missile colors can be enabled using 
CEL0RO3-P&M-0N (no stack effect)* After COLORED-PtthON is executed, where players 0 and 1, or 
players 2 and 3 intersect, their colors will be CEed. 

Use of the fifth player can be enabled by executing FIVE-PLAYERS (no stack, effect)* Note that 
FIVE-F1AYERS only assigns the color of playfield color 3 to all the Missiles*, they Must still be 
positioned together by the prograMMer* 

ERASE-P&M will fill all of player-Missile Mewory will zeros, but art easier way to reMove players 
and Missiles froM the screen is to set their horizontal positions to zero* 



IV. 10 Plsyei — Missile 



P .Z 




AMD! 



n addr — 

Performs the logical and of the contents of addr arid n, leaving the result as the new 
contents of addr* Used with both shadowed and unshadowed players arid Missiles* 



CtLORED^aHHFF — 

Disenables fifth arid sixth player-fissile colors* 

Used with both shadowed arid unshadowed players and Missiles* 

COLORED-P&M-ON — 

Enables the use of fifth and sixth player Missile colors* Ifoen this is called, where 
player 0 and player 1 intersect, arid where player 2 and player 3 intersect, their colors 
will be ORed* 

Used with both shadowed and unshadowed players and Missiles* 

DISENAE1I-KISSILES — 

Disenables the Missile graphics* Used only with shadowed players and Missiles* 




DISENABLE-P&H — 

Disenables player-Missile graphics* 
Used only with shadowed players and 



DISENAE1I-PLAYERS — 

Disenables the player graphics* 

Used only with shadowed players arid Missiles* 

ENABLE-MISSILES — 

Enables the Missile graphics* 

Used with both shadowed and unshadowed players and Missiles* 



ENABLE-P&M 



Enables player-Missile graphics* 

Used with both shadowed arid unshadowed players and Missiles* 



ENABLE-PLAYERS — 

Enables the player graphics* 

Used with both shadowed and unshadowed players and Missiles* 



ERASE-P&H 



Stores zeros into all of player-Missile MeMory* 

Used with both shadowed and unshadowed players and Missiles* 



FIVE-F1AYERS 




Assigns the color of playf ield color 3 to all the Missiles allowing theM to be Moved 
together as a fifth player (otherwise, the Missiles take the colors of their respective 
players)* 

Used with both shadowed arid unshadowed players and Missiles* 
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FOUR-PLAYERS — 

Assigns each Missile the color of its respective player. 
Used with both shadowed arid unshadowed players arid Missiles* 

FROH-SHADQH-f — addr 

A variable which holds the address of the code routine attached just before 
SHADOW-PLAYERS, The paraMeter field of FRQH-SHADOW-P Must not cross a IK boundary, 

GENTLE-GR, graphics * — 

Switches graphics Modes without bothering the players and Missiles, 
Used with both shadowed arid unshadowed players and Missiles, 

GRAFPO — addr 

A constant that returns the address of player O's graphics register. Used with both 
shadowed arid unshadowed players arid Missiles, 



HPOS! 



HPOSPO 



HISSILEJ 



NOT 



OR! 



PLAYERJ 



PLAYERS 



x n 



Moves player n to the horizontal position x on the screen. 

This word is used both with shadowed and unshadowed players and Missiles, 



— addr 

A constant that returns the address of player O's horizontal position register, Used only 
with shadowed players and Missiles, 

— addr 

A variable which contains the address of the beginning of Missile Memory. 
This word is used in both shadowed arid unshadowed players and Missiles. 



n — m 

Returns the ones coMplewent of the top of the stack., 
n addr — 

Per for ms a logical or on the contents of addr and the value n. Leaves the result as the 
new contents of addr. Used with both shadowed and unshadowed players and Missiles. 

— addr 

A variable which holds the address of the beginning of player O's Mewory. SiMilarly for 
PLAYER.l t PLAYER.2, etc. 

These words are used with both shadowed and unshadowed players and Missiles. 

— addr 

A variable which contains the address of the beginning of Missile Memory. This is the 
saMe as HISSILEJ, but it will Make code clearer if this is used when FIVE-PLAYERS is 
enabled. 

This word is used with both shadowed arid unshadowed players and Missiles. 



PM-RESOLUTION n — 

Sets player-Missile resolution} takes either n=l for single-line resolution or n=2 for 
double line. 

This word is used with both shadowed and unshadowed players and Missiles. 



PMBASE-SHADOW — addr 

A variable which holds the page nuwber of the beginning of player-Missile MeMory. 
This word is used with both shadowed arid unshadowed players and Missiles* 



S-HPOSPO 



S-SIZEPO 



SET-P&M 



PRIORITY n — 

Sets the bit in GPRIOR which controls the priority of objects on the screen* An object 
with higher priority will appear to be "in front" of an object with lower priority* 
Used with both shadowed and unshadowed players and Missiles* 

— addr 

A constant which contains the "shadow" registers for the player-Missile horizontal 
position registers HPQSPO, HP0SP1, etc* 
Used only with shadowed players and Missiles* 

— addr 

A constant which contains the "shadow" registers for the player-Missile size registers 
SIZEPO, EEEP1, etc* 

Used only with shadowed players arid Missiles* 
addr* n — 

Enables player-Missile graphics* setting the start of player-Missile MeMory to addr, and 
the resolution to n* SET-P&M also sets variables MISSILE J, PLAYER J* PLAYER.lt etc*, and 
clears player-Missile MeMory* 

Used with both shadowed and unshadowed players and Missiles. 

SETUP-SHADOW-P&K — 

Attaches SHADOW-PLAYERS to the iMMediate MBLANK routine. SETUP-SHADOW-P&M Must be 
re-enabled after a reset. 

This word is only used with shadowed players and Missiles. 
SHADOW-PLAYERS — 

A MELANK routine that reads values froM the "shadow" registers S-HPOSPO and S-SIZEPO to 
the player-Missile horizontal position and size registers. SHADOW-PLAYERS also shadows 
the graphics control register GRACTL in S-GRACTL. 
This word is only used with shadowed players arid Missiles. 



SIZE! 



size, n — 

Changes the width of player r»* Width will be either single width (size=0 or 2), double 
width (size=l), or quadruple width (size=3)* 

This word is used both with shadowed and unshadowed players and Missiles* 



WAIT-UB 



Waits for the next vertical blank, arid returns control after interrupt ends. Used only 
with shadowed players and Missiles. 



^^^^^^ 
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Chris Helck of the Swarthaore Trigonometry Project designed a set of "shadowed" player-rtissile 
words to correct two problems which occur when using unshadowed players and rtissiles* The first of 
these happens when display list interrupts are used to display a player in two (or wore) parts on the 
screen* With unshadowed players, this requires two display list interrupts, one in the Middle of the 
screen to change the players horizontal position, arid one at the botton or top of the screen to set 
it back to its original position* Shadowing the horizontal position registers rtak.es only one display 
list interrupt necessary* The second problew is that HPOS! writes directly to the horizontal 
position register* As a result, if it is being called while a player is being drawn, the botto* part 
of the player will hove before the top, producing, briefly, a ragged line, ratter than a straight 
line* Shadowing the players renoves this problem In addition to shadowing the horizontal position 
registers, SHADOH-PLAYERS also shadows the size registers arid GRACTL* 

In order to use the shadowed players, the only extra step is to call SETUP-SHAD0I4-P&M (no stack- 
effect) after each RESET* All of the urr-shadowed player-missile words have the sane function in the 
shadowed words* 

The vertical blank routines nust be loaded before loading the shadowed player-trissile words. 




i 



IV + 12 TEXT WORDS FOR DISK STORAGE 

OF TEXT 



The text words provide 3 convenient Method of storing blocks of text on disk, arid noving then 
easily into nenory* The text is included in the definition of words defined by *T (for node 0 text) 
or ST12 (for Modes 1 or 2 text)* The text nust begin on the line following the IT (or **T12), and the 
end of the text is signaled by a seni-colon at the beginning of a line* For example} 
JT GEORGE 

This is the text which 
is being stored in this 
example called GECff\*GE 

; 

The text in words defined by *T12 should not have nore than 20 characters to a line J characters 
beyond the 20th are ignored* 

The text can be any nutter of lines long* If the text will not fit entirely on one screen* 
sinply write to the botton of the first screen and continue at the top to the next screen* Do rat 
use a " y • 

Wren a text word is compiled (i*e* the screen containing it is loaded) ♦ the definition in the 
computer lienor y does not contain the actual text* Rather* it contains a pointer to the screen on 
which the text is stored* Thus, when the word is executed it is essential that the disk containing 
the text is in the disk drive* 

When 3 text word is executed it expects an address on the stack* arid it noves the text fro* disk, 
to nenory beginning at the given address. Since the primary use of the text words is to wove text on 
to the video display, there are three words designed to return the appropriate address* 

n HlhDCfrHJhE returns the address of the nth line of the text-window (assuring one is in use)* 

n SCREEN-LINE returns the address of the nth line of a node 0 screen, while 

n SCREEN-LINE12 does the sane for node 1 or 2 screens. In all cases the top line is nunber 0* 

Thus 

3 SCREEN-LINE GEORGE 

would put the text in the definition of GEORGE on a node 0 screen, beginning at line 3 (i.e* 4th line 
fron top). 

To increase flexibility, the pointers that are conpiled into text words are not the absolute 
screen nunber s on which the text appears, but are instead offsets fron the screerr-nunber stored in 
the variable TEXT-BASE. It is therefore necessary to put the word INITIAL-TEXT-SCREEN at the top of 
the first screen which contains words defined by # *T or !T12* This sets the variable TEXT-BASE to the 
correct value* 

* 

The advantage of this systen cones fron the fact that it is sonetines desirable to load a 
progran fron one disk and store the text on a seperate disk (this is especially true if the progran 
is preconpiled)* To do this, sinply reproduce the screens containing text words on the text disk.* 
Hake sure that they are in the sane order and relative position as they are on the progran disk* It 
is not necessary, however, to put the text on the sane nunhered screens* Instead, store the nunber 
of the first text screen (the one that contains the word INITII^-TEXT-SCREEN) in the variable 
TEXT-BASE* 



IV. 1Z TEXT WORDS, P. 2 



It is sonetines desirable to bring a screen containing text into the buffer at socie point before 
the text is actually used (so that the disk, drive does not have to operate at that point). This is 
done using the word TEXT-BUFFER. For example, if GEORGE is a text word, the expression 
S BUFFER-EXAMFIE 

' GEORGE TEXT->6UFFER 



♦ 

i 



will bring the screen containing GEORGE'S text into a buffer* Note the fornat carefully? first a ' 
(tic), then the teat word, then TEXT->BIIFFER* 

One final note 5 all of the text words are designed to use 4 space Margins in node 0 (32 
character lines) • This is particularly easy to work with when the GE editor is enployed. 

. The Text Words were prograiwed by David Fristrow. 



TEXT->BUFFER pfa — 

Calls frott disk to buffer the screen containing the text word with the given pfa* Usually 

used in the fornatt 

' XXXXX TEXT-/RFFER 
where XXXXX is a word defined by JT or tT12, 

HODEO — addr 

A variable used as a flag by the text words* 

1ST) fig — 

The nain component of JT and 5T12« A defining word* Compiles fig (l=*»ode 0, 0=«ode 1 or 

2), screen nunber of text (counting frow TEXT-BASE), and line nunber of first text lire. 

During run tine, words defined by (*T) nove text froh disk, to nenory, beginning at the 

address on the stack (usually sone part of screen nenory). 

JT 

A defining word, used in the forhat \ 
}T XXXXX 

The text which you want to store on disk 
5 

Hote that the seni-colon mjst be at the beginning of its line. IT compiles into the 
definition of XXXXX a flag to indicate the text is in graphics node 0, the nunber of the 
disk screen the word is defined on (counting fron TEXT-BASE), and the nunber of the screen 
line on which the text begins. Words defined by IT are used in the format*, 
addr XXXXX 

This woves the text fron the disk to nenory, starting at addr. 

IT12 is the graphics nodes 1 and 2 equivalent to *T* It is identical to **T except it 
compiles a flag indicating Mode 1 or 2 rather than node 0* Because node 1 or 2 characters 
are wider than node 0, the text should not exceed 20 characters to a line* 

mmftL-TEXT-SCREEN — 

Stores the value of BLK on TEXT-EASE. It should be used at the beginning of the first 
source code screen which contains definitions of text words defined by JT or JT12. 



JT12 
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SCREEN-LUC n — addr 

Returns the address of the nth line of 3 graphic Mode 0 screen (with top line being zero). 



SCREBMPC12 n — addr 

Returns the address of the nth line of a graphic node 1 or 2 screen (with top line being 

zero) ♦ 

TEXT-EASE —addr 

A variable used by the text words to contain a pointer to the first disk screen which has 

words defined by tT or JT12 on it* 



HI1COHJME n — addr 

Returns the address of the heginring of the nth line of text 
zero) ♦ 



(with top line being 



IV + 13 TEXT COMPRESSION TEXT WORDS 

Effective use of text on the TV screen requires a great deal of waste space* Readability is 
enhanced by writing in short phrases rather than 40 character lines, by small paragraphs, generous 
indentations, and by writing only or. every other line* The Text Compression Text words allow you to 
get by with this without exacting a price in disk storage - typically we have 1/3 to 1/4 as many 
compressed text screens as "source" text screens* These words also allow the same hardy Manipulation 
of text as do the regular Text Words* 

In general, you would use the regular Text Words when developing an application (please see 
Section IV* 12)* Text Compression text Words are used in exactly the sane fashion as regular Text 
Words, arid no changes need be made with two exceptions 4 * (1) The word END-TEXT Must be added 
immediately following your last JT or 5T12 word* (2) You can force the usage of a new text screen 
(in order, for example, to avoid disk operations at an infelicitous time) by inserting the word 
NEW-SCREEN before a 11 or ST12 word* 

To make up a disk using the Text Compression Text Words, just load those words (FORGET ting the 
regular JT words, if necessary). Then choose a screen number for the first screen of compressed text 
and store it in TEXT-BASE # Subsequent screens will be filled downward from this - we fill disks with 
compiled code upward arid compressed text downward* If you prefer your screens to be filled in 
increasing order, instead, there is an obvious change you can make in MCWE.TO*DISK arid one in 
NEXT .SCREEN* 

- 

Now load yoi.tr JT and JT12 words* Various messages will inform you of the progress of the 
compilation, terminating in "END TEXT COrPHATION" ♦ Proceed to load your non-text words, as in the 
regular Text Word context* 

Behind the Scenes 

The Text Compression Text Words work as follows* When compiled there is an Encode Buffer which 
requires $420 bytes starting at EBUFF* START (currently set to $A400 - change if you're already using 
that area of memory)* Compressed text is collected in the Encode Buffer in contiguous strings of the 
form*. 

bbnncccc***c 

where bb is the number of blanks to be written to screen, rm is the number of characters following, 
arid cccc***c are those characters in Internal form* Thus, decoding consists of writing the specified 
number of blanks arid then CMOVEing the character string to screen memory* Setting the number of 
blanks bb to -1 is used to signify that the next screen of compressed text is to be brought in* For 
example when the Encode Buffer has been filled everthing up to the overhanging string is sent to the 
FORTH buffer arid a -1 is tacked on at the end. 

The end of a **T or !T12 word is indicated by placing a 0 in the "number of characters" slot rm* 
A text word defined by IT or 5T12 returns an address to a table containing the screen offset, 
character offset in the screen, and a Mode 0? flag* 



These words require $ from the Miscellaneous Words* 
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— addr 

Variable which holds the nunber of characters which are neither leading nor trailing 
blanks in a line of text on a CE screen ♦ 



— addr 

Variable which holds the nunber of leading blanks in a line of text on a QE screen* 



♦LEADING 



addr — count 

Calculates the nunber of leading blanks in the text line starting at the given buffer 
address ♦ 



— addr 

Variable which holds the nunber of trailing blanks in a line of text on a QE screen* 



(IT) 




conpilet flag — 
run' addr — 

At compile tine this defining word encodes a ST word for hode 0 if flag is 1, arid Hode 1 
or 2 otherwise* At run tine, the word is decoded starting at screen nenory given by addr* 



Defining word which at conpile tine ericodes text word with line length arid nargins set for 
Hode 0* At run tine the text word decodes at the nenory address on top of the stack* 



Defining word which at conpile tine encodes text word with line length arid nargins set for 
Hode 1 or 2* At run tine the text word decodes starting at the nenory address on the top 
of the stack* 



B.LINE 



Encodes a line of blanks (i*e* 
B.PTR)* 



nunber of blanks to the value at H*PTR and updates 



B.PTR 



c 



— addr 

A variable which during encoding holds the address in the Forth disk buffer (between $500 
arid $CF) of the next text character to be encoded* During decoding it points in the 
Forth disk buffer to the next text character* or to numeric infornation between character 
strings* 
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DECODE 



addr flag s.off c.off — 
Takes screen given by offset s*off and reads to Forth buffer, sets B*PTR fro* BLOCK and 
offset c*off . DECODE* LINE starting at addr until EOT? is set to 1. Compiled for Hode 0 
if flag is U 



DECODE* LINE 



Writes on the TV screen the nunber of blanks stored at B*PTR t then CMQVE the number of 
characters stored at B.PTR+2 arid starting at B.PTR+4. If 0 characters, set EOT? to 2. 



EE1IFF* START — addr 

Constant pointing to beginning of the IK Encode buffer* 



ENCODE 



Encodes text of a »T word until a "}" is encountered as the first character in a line on a 
QE screen* 




ENCODE* CHARS r. — 

ttoves next n characters fron Forth buffer to Encode buffer* and transforms fro* AT ASCII 
to INTERNA* Increases pointer in both buffers by n. 



ENCODE. LINE 



EhD* 



Encodes a line of text fro« the Forth buffer and moves IN to the next line* 



Stores 3 0 in the "nuttber of characters" position in the Encode buffer and troves M.PTR in 
positon for new word, 



END-TEXT 



EOT? 



Placed by user after last ST word to send final contents of Encode buffer to drive, 
Prints "END TEXT ENCODING" on TV screen, 



— addr 

Variable containing flag which indicates the end of a JT word* 



INTiTAL-TEXT-SCREEN — 

Placed by user prior to 5T text words to initialize S.CfFSET and M.PTR. When coMpiled it 

prints Message "START TXT ENCODING". 



( 



LINE, LENGTH 



Variable indicating the length of the line of QE screen to be decoded (32 for Hode 0, 20 
for Modes 1 and 2) . 
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L* MARGIN — addr 

Variable containing the nurtber of characters in the left Margin of the TV screen for 
decoded text (0 for Modes 1 and 2 f 4 for Hode 0). 



MOVE*TQ*DISK — 

Hoves encoded text fro* Encode buffer to Forth buffer and UPDATE* Prints Message "TS n" 
on the video screen arid subtracts 1 frm the contents of S* OFFSET* 



H*PTR — sddr 

Variable used during encoding to store the current offset position froM EBUFF* START in the 
Encode buffer* During decoding it points to the next byte in screen MeMory* 



ffiXT* SCREEN — 

Called by DECODE to read in the next encoded text screen froM disk if the "nuhber of 
blanks" position in a ericoded line is negative* 



Placed by user before a JT word (or JT12 word), this will cause the word to be encoded on 
a new text screen* Inserted by user if previous compilation of JT words has resulted in 
inconvenient disk read (e*g* in the Middle of the following word)* 



NXT*SCR? — 

Checks whether B.PTR is beyond the Forth buffer in which it started and, if so* brings in 
the next text screen to reset B*PTR* 



NONB.LINE — 

Encodes a non-blank lire of text and updates pointers* 



OVERFLOW — 

Takes the Encode buffer up to the current line and HOVE* TO* DISK* Hoves the current 
encoded line to th top of the Encode buffer and sets M.PTR to the end of the line* 



R*HARGIN — addr 

Variable containing the nunber of characters in the right Margin of the TV screen for 
decoded text (0 for Hodes 1 and 2, 4 for Hode 3)* 



H_IhE n — addr 

Returns Menory address addr of line n of Hode 0 screen MeMory (ft = 0,1,2, ♦♦♦)♦ Thus, if 
TEXT is the nane of a tT word, then* 

2 SCREEN-LDC TEXT 
will decode TEXT starting at line 3 of the TV screen* 
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SCREEN-LINE12 n — addr 

Returns nenors address addr if lire n of node 1 or 2 screen *e*ory (n * 0,1,2,...). Thus, 

if TEXT12 is a JT12 word then*. 

2 SCREEN-LDC12 TEXT12 
Hill decode TDCT12 starting at line 3 of the TV screen. 



SET, MODE flag — 

The flag is 1 for node 0, 0 for Modes 1 and 2, L. MARGIN, R. MARGIN, and LINE. LENGTH are 

set accordingly. 



S. OFFSET 



— addr 

Vcriable giving offset frow ojrrent screen to TEXT-BASE. 



TEXT-BASE — addr 

A variable set by the user to the first (arid highest numbered) screen to be used for text 

storage ♦ 




HINDOVKIHE r. — addr 

Retruns nertory address addr of line n in text window (n = 0,1, 2, or 3) for the standard 4 
line text window) ♦ Thus, if TEXT is the mm of a !T word then! 

2 HBTOHIhE TEXT 
will decode TEXT beginning at line 3 of the text window. 




See the Atari OS manual for more information on the VBLANK process* 

The Swarthmore Trigonometry Project VBLAW attaching words were developed to solve a problem 
which may occur when attaching code routines to the immediate or deferred VBLANK routines - by 
storing addresses in WBLKI or WBLKD* IF VBLAW occurs while the routine is being attached, it is 
possible that only half of the address of the routine will be updated, and the machine will crash* 
These words are a safeguard against this problem* 

To attach a routine to the immediate or deferred VBLA1& routines, first be certain that the last 
thing your routine does is jump to the previous initial VBLAI& routine (the address of this routine 
can be fetched from WBLKI for immediate or WBLKD for deferred routines)* Then, put the address of 
your routine on the stack and execute either STARTH)EFERREI>-^ or STl«T-IWEDIATE-VEW* To detach 
routines, simply execute either NO-MEDIATE-VE^ , or WH)EFEFmHflEV. Note, however, that these will 
only detach the routines which were atached after IVBLKI and IVBLKD were compiled, i*e* after the 
VBLANK screens were loaded* 




START-DEFERFOHW addr — 

Attaches the machine code routine starting at addr to the deferred VBLAW routines* The 
new routine will now be the first deferred VBLANK routine to execute* It is assumed that 
the new routine already ends with a jump to the previews initial deferred routine} 
otherwise, the system will crash. 



START-IKMEDIATE-VBV addr — 

Attaches the code routine starting at addr to the immediate VBLANK routines* The new 
routine will now be the first VBLANK routine to execute* It is assumed that the new 
routine already contains a jump to the previous initial VBLA$< routine* 



IVBLKD — addr 

Returns the starting address of the code routine which was the first deferred VBLAW 
routine at the time that IVBLKD was compiled* 



IVBLKI — addr 

Returns the starting address of the code routine which was the first immediate VBLANK 
routine at the time IVBLVKI was compiled* 



NO-DEFERREIH^ — 

Detaches all deferred VELANK routines from the VBLAW process, except for OS routines and 
routines which were attached before IVBLKD was compiled* See IVBLKD* 



NQ-IMHBIATE-VBV — 

Detaches all immediate VBLANK routines from the VBLANK process, except for OS routines arid 
routines which were attached before IVBLKI was compiled* See IVBLKI* 



IV.15 Big WTOBJ 

This version of HTOBJ works exactly the same way as the version described in Section HI A* 
except that it can create boots of rare than 255 sectors* The source code for this version is also 
in a Much wore readable form 




The word SOUND is adequate for many sound generating pur poses, but in some instances it leaves 
much to be desired. Specifically, if the sound to be produced is to vary dynamically (change volume, 
Pitch, or timbre over time) or if it has to persist for only a certain amount of time, then the 
processor will be tied up and will be unable to do anything else during the duration of the sound* 
This means that (for example) dynamic sound arid graphics are impossible to produce simultaneously 
with SOUND* 

If internet-driven sound routines are used, however, this limitation disappears* A basic 
interrupt-run sound system consists of several words* There is a word that takes parameters for a 
note from the user arid loads these parameters into sound variables* These variables correspond to 
pitch, timbre, volume, and duration (for each of the four sound channels)* Another word (written in 
assembler) is set up to run in VBLANK* This word moves the sound parameters from the variables to 
the hardware sound registers* If a duration parameter is being used, this interrupt ' routine would 
also decrement a duration counter every UBLANK (i*e*, every 1/60 second) arid shut off a channel when 
that counter reached zero. A more involved sound routine that read from a table of sound parameters 
would allow timbre or volume changes during the course of a note* 

See De Re chapter 7 for more information on sound routines. 
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IVJ7 QE USERS 



Introduction 

C£ is 3 full-screen text editor t designed and programmed by Charles A. Clinton* Written in 
FORTH, it was created primarily for the entering and manipulation of FORTH text, but it cari easily be 
used to enter and manipulate text for other purposes* It is large (about $2200 bytes of memory), but 
we find it sufficiently convenient that we include it in our boot* We provide both source code and a 
glossary, so enterprising programmers can modify the editor to their own tastes* 

• 

Because of the size of the Atari screen, 24 rows of 40 columns, one disk, "text screen" of 1024 
characters cannot fit entirely on the editor screen* The editor will only display 22 lines of text, 
but will allow you to enter data or. 32 lines* The two extra rows at the bottom of the screen are 
reserved for the prompt line, explained below* 

The editor screen can be scrolled over the text screen* When you scroll the screen up, the 
text at the top will disappear, but it has not beer, lost as it would be with the fig EDITOR* 

. 

Loading QE 

The disk "Swarthmore GE" contains GE in the boot. 

To load QE if it is not in the boot, it is necessary to first load $, ATASCmiNTERHAL, and HOME 
from the Miscellaneous Words, IV* 1* Then, one must add on IV* 3 CASE, IV* 4 Display List Assembler, 
and IV. 10 Unshadowed Player Missile Words. Then the source code for QE can be loaded* 

Beginner's Walk Through 

This section contains the basic instructions which you will need. Further commands, are 
explained in later sections of this manual. Let us suppose that you have booted with a disk which 
has QE in the boot arid that you have inserted a formatted disk to use for practice. To enter GE, 
merely type in QE arid press return. The screen will flash, arid there will appear a line at the 
bottom of the screen which says, something like "GE 0.1.1 18-June-B2". The number at the right end 
of this prompt line is the screen that you are or. ♦ In order to get to another screen, first type 
the letter S. 

The prompt line will now say, "Re Wr Ne Lk Ulk ?" and will have the screen number at the end of 
the line. Type in the new number you want, 45 for instance. The number 45 will replace the earlier 
number. Now type in "R" to read that screen from the disk. After a moment while the screen is being 
read, the bottom line will change to "Command". How, if for example you want to clear the screen, 
type "T", then "D", then "A". This will move your cursor to the top of the screen, put you into 
Delete mode, arid then delete the rest of the screen by filling it with spaces. 

After having cleared the screen let us enter new text in Insert mode. Type in "I". The word 
"Insert" will appear or. the prompt line, arid the borders of the screen will turn red. These will 
stay red as long as you are in either Insert or Overwrite modes. How, if you enter text, it will 
appear or. the screen as if you were using a typewriter. 

Until you use up all 32 lines of the FORTH screen, a new blank, line will appear when you reach 
the bottom of the page, arid the top line will disappear. You will know you've completely filled a 
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screen when no wore blank lines appear. 

Overwrite node is sometimes better than Insert Mode for editing existing text, so try switching 
modes, either by holding the CONTROL button down while typing Wi or by hitting the ESC button, 
which will put you back, in Command mode (notice the bottom lire), and then typing IT. In either 
case, "Overwrite" will appear on the bottom line* You can nove your cursor about with the arrows, 
used while holding the CONTROL button down, or by other commands explained in the Insert and 
Overwrite section of this manual. Wien the cursor is in the correct place, you can type over the 
existing text* 

When you are in Insert node, new characters are inserted between the cursor and the next 
character* In Overwrite node, hitting the carriage return will take you to the next line} in Insert, 
it will create a new line below the present one* 

When you are finished your editing, press the ESC button to return to Command node* Fro* here, 
go back again to Screen node by typing "S". If you now type "H", the screen you are on will be 
written to the disk* One nice option that Screen mode has is that you can type "N", and the screen 
you have been working on will be written to the disk, and the or* after it will be read in fro* the 
disk* Once you've typed an "N" or a "W", you will be put back into Comand node. To quit the editor 
type "Q". 

Another convenient way to enter the editor is to type the number of the screen you want to start 
with, and then type "SE"* Hore detailed information on the various modes follows* 



Command Hode 

In order to reach any other mode while in Comand node, type the first letter of the node's 
name** "S" for Screen node, "D" for Delete node, "I" for Insert node, arid "0" for Overwrite node. 
To escape back to Comand node hit the ESC key. Nornally, one should return to Comand node when not 
actually entering text* 

Command node is useful for elementary text Manipulation (e*g. typing "B" will break ore line 
into two? typing "X" will join two lines into one) and also for fast cursor Manipulations* 

Tab keys nove the cursor horizontally to tabs set eight spaces apart* Tab itself will nove the 
cursor to the right, while "A" will nove the cursor to the left* To clear a tab nark, hit Shift Tab 4 , 
to set a tab, hit <CTRL> Tab* You can jump to the next word by hitting "H", or to the end of the 
lire by hitting "E", to the end of the text by hitting "Z", or to the top of the tod by hitting "T u * 

It is possible to scroll the screen up or down in two different ways* If the cursor is at the 
top of the screen arid you hit either <CTRL> up-arrow or "U" the screen will nove up, exposing the 
line of text "above" the screen ♦ Symmetrical commands hold at the bottom with <CTRL> down-arrow or 
"H"* Hit "Y" to scroll the screen up, or "N" to scroll the screen down* Note that when you reach 
the last line of text at the bottom or the first line of text at the top, the screen will no longer 
scroll, but rather will flash and beep at you* 

In all modes, capitals and lower case commands have the same function, so that, for example, "S" 
and "s" will both put QE into Screen mode. 



Command Mode Commands 
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"T n - Hoves cursor to first line of text screen* 
"Z" - Hoves cursor to last line of text screen* 
"W" - Hoves cursor to beginning of next word* 



"E" - Hoves cursor to end of current line* 

Tab - Hoves cursor to next tab nark* 

"A" - Hoves cursor to next tab wark to the left* 

Shift Tab - Sets a tab nark in current cursor position* 

<CTRL>Tab - Clears a tab nark fro* present cursor position* 



<CTRLMJp-Arrow - Hoves cursor up one line* 
<CTRL>Dowrr-Arrow - Hoves ojrsor down one line* 



<CTRL>Left-Arrow - Hoves ojrsor left ore 
<CTRL>Right-Arrow - Hoves cursor right one character* 
ll H" - Sane as <CTRL>Left-Arrow* 

For this and the three commands that follow ♦ notice the convenient 

the keyboard* 
"J" - Sane as <CTRL>Right-Ar row ♦ 

"IT - Sane as <CTRLMJp-Arrow* 

"H" - Sane as <CTFl>Dowrr-Ar r ow 

<Return> - Hoves cursor dowri one lirre to first non-space character* 

<Break> - Sane as <Return>* 

T* -Scrolls screen up one line* 

M N" - Scrolls screen down one line* 

"I" - Shifts GE to Insert node* 

"D" - Shifts GE to Delete node* 

"B n - Breaks the current line at the cursor position. 

"X" - Joins two lines together* 

"Q" - Exits fro* QE* 



of these keys on 
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Screen Hode 

Screen node is reached through comand node by typing "S". It is intended for the handling arid 
Manipulation of entire text screens, arid for accessing the disk* This is accomplished by usirig a 
combination of nine letter cowhands, and the ten digits at the top of the keyboard* Entering 
anything besides these nine elands or the digits will cause you to return to Cohnand node. ESC is 
the dignified way of returning to CoHnand node* 

Three of the cowiands in Screen node are for the nanipulation of the screen number* Typing a 
,, + n will add 1 to the screen nunber} typing a n - n will subtract 1 fron the screen number } V is used 
to change the screeri rwnber to 0* You can't type in a negative number, arid if you want to access a 
negative screen, you Must go to 0 and keep the "-" pressed down until you reach the desired screen 
nunber ♦ 

There are three cowhands in Screen node which have to do with "locking" screens* This "lock" is 
harked or. the disk, and it tells QE that the screen involved should not be written to, though it way 
be read out into the editor* The three comands are "L", which will lock the screen you are on 
(according to screen nunber), "U", which will unlock the screen yew are on, arid "?" which will tell 
you whether a screen is locked or rot by putting the word "LOCKED" or "UNUJCKED" in the prompt line* 
This "locking" systew is only effective with QE, not with the fig Editor* 

(If you want to either "lock" or "unlock" every screen on the disk, you nay do so fro* outside 
QE* Type the drive nunber, a space and IM.0CK.ALL or LQCK.ALL to do this*) 

The last three cowhands in Screen nude are for the actual accessing of the disk.* These are 4 * "R" 
which reads frow the disk, the screen corresponding to the screen rxuhber on the proapt line, "W", 
which will set a flag for writing the revised screen back, onto the disk (unless it is write-protected 
or "locked"), and "N", which writes the present screen to the disk, adds one to the screen nuhber, 
and reads this next screen back, out into the editor* If the screen is "locked," this will cause an 
error arid put the editor back in Comand hode* 

Hotet "H" and "N" do not cause iiwediate writing to disk* To nake sure the last two screens you've 
worked on are actually written to disk, type FLUSH after you exit the editor* 



Screeri Mode Cowhands 



"L" - Locks the current screen to prevent inadvertently writing over it* 
"U" - Unlocks the current screen to allow writing it to disk* 
"?" - Checks to see whether the current screeri is locked or not* 
"R" - Reads the current screen fro« the disk* 
"W" - Writes the current screen to the disk (but see above note). 

"N" - Writes the current screen to the disk, and then reads the subsequent screen fro* the disk.* 

"+" - Adds 1 to the current screen nurtber* 

"-" - Subtracts 1 fro* the current screen number* 
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V - Changes the current screen nunber to 0* 

Screen numbers can also be entered directly, using the digits at top of keyboard. (Negative nurters 
can only be reached by subtracting fro* 0.) 

ESC - Returns EE to Cowhand node* 



Delete Hode 




Delete node is different fro* the other nodes in GE in that or* camot stay in the node but can 
only use it for one cofwand at a tine. This gives the user the feeling of having two letter comands 
instead of one* For example, to delete a line while in Cowhand «ode, you type '"DL" ♦ The "D" puts 
you in Delete f*xte, the M L H tells QE to delete the line the cursor is on, then CE puts you back into 
Cowhand node. 

Delete Mode can be reached fro* Comand, Insert, arid Overwrite, arid it returns to the node fro* 
which it was called* Thus, if one is in Insert node arid types <CTRL>"D" f which is the way to reach 
Delete rtode fro* Insert node, one would enter Delete node, but upon leaving would return to Insert 
node* (In any other node either an error or EX returns one to Comand node.) 

Delete node has six cowards besides the ESC key. Four are for basic editing! H C n deletes the 
character the cursor is on arid pulls back, the other characters on the line to fill in} "S" deletes 
all the spaces between the cursor arid the next non-space character? "W" deletes the rest of the word 
following the cursor. 



The other two cot-wands are a little different. "A" clears everything on the screen after the 
cursor, and "B" clears everything before. They are intended for wajor editing, so "B" deletes all 
before the cursor by filling in spaces, instead of pulling back, the rest of the text to fill in the 
deleted lines and letters. To clear a screen, Jump to the top or bottoa of the screen and type "D" 
arid either "A" or "B" depending on whether you are at the top or bottom 



p ♦ <£> 




Delete Hode Comands 





( 



"A" - Deletes all text after the cursor* 
"B" - Deletes all text before the cursor* 

H C M - Deletes the character the cursor is on? pulls back, the rest of the line to fill in. 

V - Deletes the line the cursor is on} pulls up the lines below to fill in the e«pty lire* 

H S" - Deletes all spaces fro* the ojrsor to the next non-space character} pulls rest of lire back, to 
fill iru 

"W" - Deletes word or part of word, frcw cursor onward, pulls rest of line back, to fill in* 
ESC - Returns to previous Mode* 
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Irisert ttode and Overwrite Hode 

• 

There are two nodes in CE for entering and editing text directly* Insert node and Overwrite 
node* They have nany connands in connon, arid other connands which are very sinilar* The nost 
inportant difference in the two nodes is that Insert node inserts text, while Overwrite node writes 
on top of existing text. If you hit the return key in Insert node, a new line will be inserted (if 
there is roon on the screen), but hitting the return key will just nove the cursor down in Overwrite 
node* Also, if you are in Insert node arid start typing in the Middle of a sentence, the rest of the 
line will nove aside as you type, whereas in Overwrite node the old text will be overwritten* 

Aside fron this difference, nost cowhands in Insert and Overwrite nodes are the sane* The 
arrows can be used, in conjunction with the <CTRL> key, to hove the cursor about the screen, arid nost 
of the connands which are found in Cowand node (e*g* H T" to nove to the Top of the text screen) can 
be used in these two nodes by holding the <CTRJ> key down while typing the conwand. Added to these 
connands are a few special ones, Shift INSERT and <CTRL> INSERT, the first of which inserts a space 
after the cursor, the second of which inserts the next character typed after the cursor* The 
advantage to the latter is that an^ character nay he inserted, including control characters which 
can't be entered via nornal text editing* 

<CTRL> "D H will put you into Delete node* (As explained in that section, Delete node will 
return QE to Insert or Overwrite node if it is called fron there)* <CTRL> T 1 will transfer CE to 
Insert node fron Overwrite node, <CTRL> "0" to Overwrite node fron Insert node. Thus, you do not 
need to go through Connand node to switch between these two* 
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Insert Hode Cwmands 
<CTRL> n T" - Hoves cursor to first line of text screen* 

<CTRL> , 7" - Hoves cursor to last line of text screen* 

CTRLyW 1 - Moves cursor to beginning of next word* 

<CTRL> U E" - Hoves a.»rsor to end of current line* 



Tab 



- Hoves ttirsor to next tab nark* 



Shift Tab - Sets a tab nark in current cursor position* 
<CTRL>Tab - Clears a tab nark fro* present cursor position* 
<CTRL>Up-Arrow - Hoves cursor up one line* 
<CTRL)-DowrrArrcw - Hoves cursor down one line* 
<CTRL>Left-Arrow - Hoves ojrsor left one character* 
<CTfORight-Arrow - Hoves cursor right ore character* 

<Return> - Adds line beneath current line arid places cursor at sane indentation as previous line* 
(If there is not space for one rtore line on screen, the cursor just aoves down one line*) 



<Break> - Saw as <Return>* 

<CTRD"0" - Shifts QE to Overwrite node. 

<CTRL>"D n - Shifts QE to Delete node* 

Shift <Insert> - Adds space after Djrsor position* 

<CTRLXIrisert> - Inserts any one character t$>ed in after current cursor position* This allows 
insertion of <CTRL> sequences that leave 



<CTRL> ,, B" - Breaks the current line at the cursor position* 

The other keys work normally* As long as there are spaces to the right, all other text will be Moved 
to the right as text is inserted* 

ESC - Returns to Cowhand node 
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Overwrite Hode Connands 

■ 

<CTRL> ir T n - Hoves cursor to first line of text screen* 

<CTRL> ,, Z" - Hoves cursor to last line of text screen* 

<CTRL>"H n - Hoves cursor to beginning of next word* 

<CTRL>"E" - Hoves cursor to end of current line* 

Tab - hoves cursor to next tab nark* 

Shift Tab - Sets a tab nark in current cursor position. 

<CTRL>Tab - Clears a tab nark fron present DJrsor position* 

<CTRL>Up-Arrow - Hoves ojrsor up ore line* 

<CTRL>Dowrr-Arrow - Hoves cursor down one line. 

<CTRL>Left-Arrow - Hoves cursor left one character. 

<CTRL>Right-Arrow - Hoves cursor right one character. 

<Returri> - Hoves cursor down one line to first non-space letter. 

<Break> - Saw es <Return>. 

<CTRL>"I" - Shifts QE to Insert rode, 

<CTRL>"D" - Shifts QE to Delete node. 

Shift <Insert> - Adds space after cursor position. 

<CTRLXLnsert> - Inserts any one character typed in after ojrrent cursor position. This allows 
insertion of <CTRL> sequences that leave graphics characters. 

<CTRL>"B U - Breaks the current lire at the current lire at the cursor position. 

Any other keys behave nornally. Text is written over existing text. 

ESC - Returns to Connand node. 
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NOTICE ! The glossary which follows is intended for hackers and the idly curious* Users of (E will 
only need the following half dozen words, all of which are invoked fro« FORTH: 

QE and SE, described above, which get you into the GE Editor 

n LOCK.ALL , which "locks" all the screens on drive n*, its cousin UM_0CK_ALL 
n LQCKJBQOT , which "locks" the boot screens on drive n 
WE , which is used like W£R£ to locate compilation errors* 



— GEO W3CABILARY 

This sets up a table to be used for the prowpt lire* This table is allotted 3*1 bytes* To 
use, follow " with a four letter header starting with a quotes, then the prompt followed 
by a quote* Thus** 

" "com mtm) 

" "SCU Re Hr He Lk Ulk Unlocked " 
There fiust he 30 characters used between quotes* 

"Kt" — addr QED 

Variable signifying the keyboard address. 

$?0F f — 

The run-tine procedure compiled by ?0F* Works like $CF, except that it takes a flag fro« 
the stack, rather than comparing two values on the stack* (See CASE glossary*) 



ZEND — n QED 

This constant holds the address of the end of the data for the current text screen* 

XF — flag QED 

Constant with value of 0, signifying False. Clarifies code* 

ZT — flag QED 

Constant with value of 1, signifying True* Clarifies code. 

/COL — addr QED 

Variable holding the number of the column the cursor is on* 

/DONE — addr QED 

Variable holding flag which is true if you are ready to leave QE, false otherwise* 

/EXTRACT — n QED 

This constant gives the memory address directly after XEI€>* Holds deleted characters for 
use with SAVE*CH and EVAS*CH* 

OTO — addr QED 

Variable holding place in the stack of deleted characters* (Must be offset by /EXTRACT). 



/IMAGE 



— n . QED 

This constant holds the location of the top of the GE display list. 



/INSERT 
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addr 



QED 



Variable holding flag which is true if EE is in Insert hode, false if not* 



/KEY 



— 3ddr QED 
Holds the value of the key pressed ♦ 



Used in the CASE structure in the for m \ 
f ?0F xxx FO 

?0F works like OF, except that it takes a flag fro* the stack, rather than comparing two 
values on the stack ♦ (See CASE glossary ♦) 

/LASTNUrfcER — addr QED 

Variable holding the number of the screen last used before the present one. 



/LINE 



/NUrBER 



/OLDDLA 



/PROMPT 



— addr QED 

Variable holding the number of the line in memory to which the current row corresponds ♦ 

— addr QED 

Variable holding the absolute value of the screen nutter « 

— addr QED 

This variable holds the address of the display list on the screen prior to EE's display 
list* This is replaced on exiting QE* 

nl — n2 QED 

This is the prompt line, set up as a table, allotted 50 bytes* It appears at the bottom 
of the screen ♦ 



/ROM 



— addr QED 
Variable holding the row the cursor is on* 



aoor 



/SMUDGE 



Variable which is 1 if the screen number is positive and -1 if the screen number is 
negative* 



— addr QED 
Variable signifying that there is a prompt* (0 if there is not)* 



/STOP! 



/TABS 



— addr QED 
Variable holding flag which says whether or not to stop the mode QE is in* 

nl — n2 QED 

Table of tabs, set originally to every eight characters. Changed by SETTAB arid CLRTAB* 



MIRD-FLAG — addr QED 

Variable which holds flag saying whether a digit typed in should be part of old digit, or 
whether it should begin again. (e*g* 35 is displayed. Should a 1 typed in become 351 or 
4). 

/WERE — n BED 

This constant points to nefwry address of the first text character to appear on the 



ALENGTH — n (ED 

Returns the length of the first row displayed on the editor's screen, not including 
trailing blanks. 

AIXOCATEJEMAGE — QED 

Puts the address of the beginning of the text in the display so that the top of the video 
screen holds the first line of the text* 

BEEP! — QED 

Flashes yellow to signify error, then returns to previous color* Sets /STOP! to true 
(i.e. 1). 



BEEP? — flag QED 

Is /STOP! true (i.e. 1 )? If so, returns true flag. 

BITJABLE r.l — rt2 FORTH 

Table containing bit logic for lock/unlock flags. There are eight elements. 

BREAKJJNE — QED 

This is only operational if there is rocm below the line the cursor for an inserted line. 
This shifts all of the line after the cursor down to the line below, leaving blanks after 
the cursor on the original line, arid blanks before the cursor on the added line. 

b — n QED 

Constant that returns code field address of BEEP! 

CASBUF — n FORTH 

This constant narks the beginning of the cassette buffer (plus 2 bits )♦ This is used for 
buffer since we don't use cassettes. 

CH! ch — QED 

Stores the character given at the locaton in rtetiory corresponding to the cursor location. 

CH? — addr QED 

Finds the location of the character in nettory which corresponds to the cursor location. 
Puts that address on the stack. 

Cm — ch QED 

Fetches the character at the location in nefiory corresponding to the cursor location on 
the screen. 

C.PSE6 — QED 

Turns off the keyboard, (i.e. won't read fron the keyboard after this). 

CLRTAB — QED 

Clears a tab nark fron current position. (Puts 0 in /TABS). 

COTOATOJJOQP — QED 

This runs continuously while in Cowiand Mode, picking up cofwands and executing then. 
Aborts when /D0f£ returns false. 

CURDQHN — QED 

Moves cursor down 1 row. 
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CURUP 



— QED 
Moves cursor up 1 row. 



DI 



— addr QED 

This is the display list for GE* It has 22 lines of Hode 2, a divider of 1 Blank, and 1 
line of Hode 2 for the prompt* 



DELETE.ONE addr — QED 

Replaces character at this address with a space* 

DEL_AFTER — BED 

Replaces all characters after cursor to end of text screen with spaces* 



DELJSEFORE 



Replaces everything ori 



screen before the ojrsor with spaces* 



DEL.CHAR — QED 

Deletes a character arid uses SAME-CH to save the deleted character in a delete buffer* 

DELJJNE — QED 

Deletes the current line arid. Moves lines below up one* 



DEL.SPACES — QED 

Deletes all spaces ftm the Djrsor to the next non-space 
ever cones first* 



or 



of the row* 



DEL.HDRD — QED 

Deletes all characters fro« the cursor to the next space* or the end of the row* 

DEXJMT — QED 

Sets up all of the DLI's , display list, colors, missiles, etc. Initializes everything 
that needs it* 



DISKIO — FORTH 

Executes the system disk handler, Assunes that the device control block, has been set up 

already < 



DISPJftJH 



This takes the norther of the screen in use and puts it on the prompt lire* 



DOWN 



— QED 

If the cursor is at the botto* of the display, this Moves data up one line without 
changing cursor (unless there is no hore data to scroll), otherwise this just roves cursor 
down one line* 



ED_COMMAND — QED 

Executes cowrands entered in Cormand Hode* 



ENDJ 



Moves cursor to last non-blank character of current line. 



EVAS CH — ch QED 

Retrieves character at address of /EXTRACT + /EXTRACT? and subtracts ore fro* /EXTRACTP. 



FLAGs — n FORTH 

This constant leaves the location of the lock arid unlock flags* 

GET.BYTE scrri — addr nask FORTH 

Gets the appropriate address arid nask for the lock/unlock bit of this screen* 

GET.KEY — ch QED 

Gets the value of the key pressed arid puts its AT ASCII value on the stack* Also stores 
this value in /KEY* 



113 



— n 

This checks to see if the lire is indented. It returns the nunber of spaces indented. 

*T_CHAR ch — QED 

Inserts a character in row after cursor, if there is room* 



INSERT J>*AR_R ch — 

Takes a character arid tries to insert it to the right of the cursor* If it is at the end 
of the row, it inserts a new line and inserts the character at the first column* 

INSERT_D(MI — • QED 

Inserts a line beneath Djrrent one if there is roo«* (i»e* blank lines at bottom of data 
screen*) Used by INSERT-LUC. 

INSERT JJNE — QED 

Inserts a line beneath current one, if possible, and noves cursor to indentation of 

■ 

previous line* 



KBOTTOM — QED 

Puts cursor at first colum of last line of text screen, 

KDELETE — QED 

Puts QE in Delete Mode, arid puts Delete prompt on prompt line* 

KTXSERT — QED 

Sets /INSERT to true and invokes TEXT. 

KJOIN — QED 

Joins together current line arid line below. 

KOVERWRITE — QED 

Sets /INSERT to false and invokes TEXT. 

KQUTT — QED 

Sets /DONE to true, alowing QE to quit, 

KRECOVER — QED 

Recovers a character fro* the deleted /EXTRACT buffer using EVAS-CH. 

KRETURN — QED 

Hoves down one line if possible and to the first non-blank character (using INDENT?), 

KSCREEN — QED 

Puts QE into Screen Mode, froti Comand Mode only, and sets /WEIRD-FLAG to false to allow 



nunbers to be entered properly. 

KSCROLLDOWN — QED 

Used for scrolling the screen in Cofwand Node* Uses ROLLIF* 

KSCROLLUP — QED 

Used for scrolling the screen in Cownand Hode* Uses RQJJXHW* 

KTOP — GED 

Puts cursor at first line of text screen, in the first colum* 

LEFT — tED 

Hoves Djrsor one colunn to the left, unless it is at the first colunn* If it is, this 
Moves the cursor to the last column of the row above, if there is a row above* 



LENGTH — n QED 

Returns the length of the first line of the text screen, not including trailing blanks* 



LOCK scrr. — FORTH 

"Locks" one screen by setting a bit in the cassette buffer (unused), thus preventing 
writing that screen to the disk fro« QE* 

LOCKED? scrn — FORTH 

Returns "Locked" if the screen is locked, and "Unlocked" if it is unlocked* 

LOCK.ALL drive — FORTH 

Locks all screens on given drive, so that none can be written to in QE* 



LDCKJ500T drive — 

Locks all screens fron -11 to the end of the boot, (this Must be set into word) so that 
the boot screens cannot be written to fron QE* 

L0CKJJ3QK scrn — flag FORTH 

Sets flags to 1 if the screen is locked* 0 if it is unlocked* 

HAPJEtT scrn — nask offset FIFTH 

Haps the screen nunber to the lock/unlock bit to which it corresponds* 

HAP.CH! ch — QED 

Changes ATASCIE character value to corresponding Internal value before storing it in 
rtewory* 

mjmm ch — ch qed 

Identifies upper arid lower case letters, then naps letters to the comands they should 
cause to occur* 

WJ9CREEN scr — scr drv FORTH 

Figures out which drive a screen is on} gives error if it is not a possible screen* 

NEXT_SCREEN — QED 

Writes current screen to disk using HRTH-SCREEN, reads in subsequent screen using 
READ-SCREEN and adds 1 to MWER* 

NGET — n QED 
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Returns the screen nunber being used* 

open.k: — BED 

This opens the Keyboard. 

PROMPT addr — QED 

T3k.es address of a prompt Message , finds its total length arid Moves it to address of 
/PROMPT. Sets /SMUDGE to true. 

QE — FORTH 

Puts into QED vocabulary, uses DEXJXET to initialize everything, arid uses XED to enter 
the editor, arid later to exit frcm the editor* 

GED — FORTH 

Establishes QED as the CONTEXT vocabulary* 

READ JLAGS drv — FORTH 

This word reads the lock, and unlock flags frcm the disk in given disk drive* 

REAELSCREEN — GED 

Reads screen held in /NLfrBER (sign held in /SIGN) fron disk* Puts Reading* ♦♦ prompt on 
proript line* 

RIGHT — QED 

Moves cursor to the right one column, unless it is at the last column* If it is, this 
Moves the cursor to the first column in the row beneath, if there is a row beneath* 

ROLLDOW — QED 

Scrolls screeri of text upward unless it is at bottom Does not hove cursor* 

ROLLUP — BED 

Scrolls screeri of text downward unless there is no «ore above current line* Does not hove 



♦ 



SCREENJUOCKED? ~ QED 

Checks to see whether the current screen is locked* If it is, puts "Locked" in inverse 
video on prompt line, if not, puts "Unlocked" on pronpt line in inverse video* 

SDIGIT — QED 

Tak.es input and translates it to decimal numbers that /NUMBER can hold* 

SE scrr. — FORTH 

Given a screen nutiber, this simultaneously enters GE arid causes the screen to be read in* 

SETDOWN.DL — QED 

Reconstructs display list on screen prior to G£'s display list* Uses /OLDDLA* 

SETTAB — QED 

Sets tab Mark in current position. (Puts 1 in /TABS). 




SETUP.DL — QED 

Puts address of old display list in /OLDDLA*, sets up Dl as display list. 

SET.COL col — QED 




SETJJDC 
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Given a column number, this puts it in /CCL arid moves player 0 (which forms the cursor) 
over to that column* 



n — (ED 
Puts line from memory on screen} puts line number in /LINE* 



SET.RDH row — QED 

Sets up the cursor , using player 0, at the row, and puts value in /ROW* 

SHEXDIGIT — QED 

Takes hex numbers as input and translates then to numbers that /Nl&iEER can hold* 

SINCREtfENT — QED 

Increments /NlftBER by 1 or -1, depending ori the sign (held in /SIGN) * 



SMINUS 



— (ED 
Subtracts 1 from ojrrent screen number* 




SAVE.CH 



— flag QED 

Checks to see if /STOP! is true, or whether ESC has been hit* Returns true if either is 
true* 

ch QED 

Saves a character in address found by adding /EXTRACT arid /EXTRACT?* Adds one to 
/EXTRACT? ♦ 



STOTAL — (ED 

Puts zero in /NUMBER and 1 in /SIGN* 



TAB 



TAB 1 





— QED 
Moves the cursor right to the next tab mark* as found in /TABS* 



— QED 
Puts a flag in /TABS at current position* 



TABJBRD 



Pops to beginning of next word* Will continue* line after line* till it finds a non-space 
character* 



TEXT 



TEXTJS 



— QED 

This word is used to go into Insert or Overwrite Mode from Comand Mode* It oversees the 
various commands that can be used in those modes* Gathers together marry little words for 
use in actual editing* 

— QED 

Insert Mode* Deletes character to left of Djrsor, drawing back, rest of line to fill in* 
Overwrite Mode** Overwrites character to the left of cursor with a space* 



TEXT_CH ch — QED 

If QE is in Insert Mode* this inserts the character to the right of the cursor using 
B^ERT-CHAR-R* 

If in Overwrite mode, this writes over the character under the cursor, moves cursor right 
using RIGHT, and saves overwritten character with SAME-CH* 
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TEXTJMBERT QED 

Puts Irrsert prompt in prompt line, and sets /INSERT to 1 (true)* 

TEXTJWER — QED 

Puts Overwrite prompt on profit line, arid sets /INSERT to 0 (false)* 

TEXT.RETURN QED 

If QE is in Overwrite Hode, this noves cursor to first non-blank, character on lire below 
current line. If CE is in Insert Hode, this inserts a lirie below current one, space 
per witting, and Moves cursor to indentation of line above* 

UNTAB — QED 

Moves the oirsor to the next tab nark to the left, as found in /TABS. 



UNTAB.WORD — QED 



Hoves left till it finds a non-space character* Moves up screen till it finds a non-space 
character or the beginning of the screen. 

UNLOCK scrr. — FORTH 

"Unlocks" a given screen by setting a bit in the cassette buffer, thus allowing one to 
write that screen to the disk, in GE* 

UNL0CKJ1L drive — FORTH 

Unlocks all screens on given drive, so that all can be written to fro* GE* 

UP — QED 

If the Djrsor is at the top of the display, this *oves data down one lire without changing 
cursor (unless there is no «ore data), otherwise it just *oves the cursor up ore row* 

VECTOR nl — rtZ QED 

This is the table (54 bytes long) containing the address of the actual keys for entering 
cot-wands in CoHMand Hode* 



WE scrn row col — 

Recovers QE after disk errors* This will put GE up with scrn as the screen, and the 

cursor at row arid col* 

WEIRD.CHECK — QED 

If /WEIRD_FLAG is false, this zeros the current screen nunber arid sets AORD.FLAG to 

true* 

WRITEJLAGS — FORTH 

Writes the lock/unlock flags to the disk* 

WRITE.SCREEN — QED 

Writes screen held in /NUMBER (sign held in /SIGN) to disk* Puts "Writing* ♦♦" prompt 
on prompt line* 



XED — QED 

Puts in original QE proupt giving Revision nurtber, etc. Sets up everting, initializes 

everything, puds into COMMAND JJDOP, 



HOTaT to write good forth 



FORTH suffers from a combination of bad press arid bad programmers* It is actually easier to 
write good FORTH than good anything else, since it is flexible, imposes few restrictions, and 
extracts no penalty for short programs, (Short programs, incidentally, are where it's at - breaking 
things up into small, sensible, lucid pieces is a key to good programming)* 

« 

Hha write good FORTH? 

Good code is faster to write, if you consider total time, since it comes from clear thinking and 
good organization, arid it is much easier to debug. You can understand and modify good code in 
amazingly shorter time* 

Finally, you're much more employable if you write good code* Should a prospective employee tell 
me that he or she prides him or herself in writing good, clear, maintainable, well-documented FORTH I 
would, after picking myself up off the floor, endeavor to hire the person or. the spot. 

How to write good FORTH: 

You need to (1) know what good FORTH is, (2) discipline yourself to write it* Item (1) will be 
addresed next* For (2), I've observed that a few thoughtful rewritings of a reasonably sized piece 
of code will not only help a decent programmer understand what good code is, but will also establish 
the necessary habits so that writing passable code becomes almost automatic, and good code a distinct 
possibility* 

What is good FORTH? 

Good FORTH consists of short, well thought out pieces* A word should rarely take up more than 
half a screen* If you use more than that, see whether you can break, up the word into smaller, more 
coherent pieces* A good FORTH word is one which is easy to understand, and which you might be 
tempted to use again elsewhere* 

Good FORTH is vertical, not horizontal* That is, there are few words per line and the lines are 
left-indented in an intelligent fashion. DOs and LOOPs, BEGINs and UMTLs, IFs, T*£Ns, and ELSEs, 
etc* are all left justified, with inner groupings to the right of outer ones. Take a look, at the 
Swarthmore source code to see what this means. 

Each line should contain no more than a single idea. 

A comment accompanying each word should show its effect on the stack, preferably with helpful 
mnemonic symbols for the stack, elements* 

Words should be liberally sprinkled with comments. Hore lengthy comments can be put after the 
>" or "}S". The best code is almost self -documented. 

The first line of a screen should consist of a comment which describes the contents of the 
screen. You should rarely start with more than half a screen full of code* 

Will you go broke buying the number of disks necessary to write good FORTH? Hardly* Even in 
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this expansive forn, FORTH gets you a lot of Mileage ♦ Horeover, few itens connected with computers 
are as cheap as disk space* Finally, truth to tell, revisions and reworking usually result in 
screens filling up More than the nir.iMal reconnended (starting Minimally gives you rooM for such 
expansion) i 

FORTH is supposedly a "stack oriented" language, but the prograMMer should not be stack 
oriented. Juggling several elements or. the stack can cause a surprising nuriber of errors* In almost 
all situations, it's Much clearer and leads to Many fewer errors if you introduce sensibly naned 
variables* It is hard to find a situation when such a practice will Measurably slew down a prograM* 
It is possible to juggle stack elements by sending the* to and fro« the return stack (it's possible 
to do lots of wild things in FORTH), but it's usually just not worth it* 

If you siMply Must play with several iteMs or. the stack, you're probably best off Making up 
special stack. Manipulation words* If a word deals with several iteMs on a stack, I've also found it 
very helpful to put in full connent lines within the word which show the stack, changes in clear 
Mnehonics* 

Hell-thought-out nanes can cor.tr ibute intensely to good code* It's worth spending tine waking up 
useful nanes (self-docunenting code, again)* One helpful approach is to try to nane what the word 
does, not how it does it* .Don't use an unidentified nunber in a word. Either identify it in a 
content or define a constant (with a good nane) arid use it in the axle. 

Avoid abbreviations when you're writing code. The extra typing is trivial and the clarity 
introduced is considerable. It's fair and reasonable to introduce abbreviations in a 

testing/debugging session, however. 

• 

Is our code good? 

It varies. It's getting better. At first we conttitted the negation of the above ideas. Look 
over our source code and see what you like and what is clear. There are probably 8 different 
prograMMers represented on the SwarthMore disks, so there are lots of different styles, ideas, arid 



Further thoughts or. writing good FORTH are to be found in Leo Brodie's Starting FORTH* 
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n X EDIT 

EDITOR 

SCR 

L 

N 

LL 
UL 

DOIT 



e 



- Enter editor vocabulary on scr^|n n 



RECEIVED 

NOV 1 o 1982 

SPECIAL PROJECTS 



- VOCABULARY name - used to get to the Editor words. 

- VARIABLE containing the current edit screen ^T*"^ 



- List current screen. 



- List next screen. 



SRC DEST COPY 



FIRST LAST SHOW 



n LIST 



Line Edit Functions 



n TL 



n HL 



n DL 



n IL 



n RL 



n SL 



- List lower 8 lines for screen editor. 

- List upper 8 lines for screen editor. 

- Take the top 16 lines on the TV display and put into 
the upper or lower half of the edit SCR. (whichever 
was last displayed). Use the colleen cursor and edit 
keys to change the screen. Move the cursor to the 
DOIT line and hit RETURN. 

DO NOT HIT RETURN while editing the LL or UL screens. 

- copy block SRC to block #DEST. 

- list all blocks inclusive. 

- set SCR to n and list the block. 



n BL 



n SCR CL 



n $ 



n % 



FLUSH 



- Type line n and save it in PAD. 

- Hold line n in PAD. 

- Delete line n - save it in PAD. 

- Insert PAD after line n. 

- Replace line n with PAD. 

- Spread to create blank line n by pushing every thing 
down and losing line F. 

- Blank line n - not saved in PAD. 

- Move line n of Screen #SCR to PAD. 

- Put text following $ up to RETURN onto line n. 

- Insert text following % up to RETURN after line n. 

- RETURNS to FORTH Vocabulary. Writes out changed 
blocks. 



Currently 7/8/80 8 Load loads the assembler, Ed Logg's Colleen I/O and 
Graphics words and this Editor. 



1+! 
1- 

OSET 

2* 

2/ 

CHH 

HH 

CH? 

H? 



TBL 



ALLOC 



ARRAY 



S? 
RP 
R? 

BDUMP 




(addr->) 
(n-? n-1) 
(addr-» 
(n n) 
(n ~f n) 
(b ^ ) 
(u ^ ) 
(addr ) 
(addr ) 



( ~7> n) 



(n -» ) 
(n ) 



( -> ) 
( -?n) 

( -y ) 

(addr ,addr -~> ) 



ATARI FIG ADDITIONS 
(From DECUS) 



^ - 



add one to word at addr 
subtract one from TOS 



set word at address to 0 



mult. TOS by 2 
div. TOS by 2 



faster than 



type value of LSB of TOS as 2-digit HEX- 

type value of TOS in unsigned HEX 

type value of byte at addr in HEX 

type value of word at addr in unsigned 
HEX 

return Index for next outer most DO-LOOP 

;defines ROM table (like DECUS, CALTECH 
IARRAY) 

allocate n words in RAM 

CREATE named ARRAY, n words long, returns 
addr of first element when exe 

TYPE contents of param stack, without removing them 

point to TOP of RETURN (control) stack 

TYPE contents of return stack (non-destructive) 

Display contents of addr to addr (inclusive) 
always in increments of 8 bytes. 



TERMINAL INPUT-OUTPUT 



.R 
D. 
D.R 
CR 

SPACE 
SPACES 

DUMP 

TYPE 

COUNT 

7TERMINAL 

KEY 

EMIT 



WORD 



n - ) 

n fieldwidth — ) 

d - ) 

d fieldwidth - ) 

- ) 

- ) 
n - ) 

- ) 

addr u — ) 
addr u — ) 
addr - addr+1 u ) 

- f ) 

- c ) 
c - ) 
addr n - ) 

c - ) 



Print number. 

Print number, right-justified in field. 
Print double-precision number. 
Print double-precision number, right-justified in field. 
Do a carriage return. 
Type one space 
Type n spaces. 

Print message (terminated by "). 
Dump u words starting at address. 
Type string of u characters starting at address. 
Change length-byte string to TYPE form. 
True if terminal break request present. 
Read key, put ascii value on stack. 
Type ascii value from stack. 

Read n characters (or until carriage return) from input to address. 

Read one word from input stream, using given character (usually blank) as delimiter. 



INPUT-OUTPUT FORMATTING 

NUMBER ( addr - d ) 

<# ( - ) 

# ( d - d ) 

#S ( d - 0 0 ) 

SIGN ( n d - d ) 

#> ( d - addr u ) 

HOLD ( c - ) 



Convert string at address to double-precision number. 
Start output string. 

Convert next digit of double-precision number and add character to output string. 
Convert all significant digits of double-precision number to output string. 
Insert sign of n into output string. 
Terminate output string (ready for TYPE). 
Insert ascii character into output string. 



DISK HANDLING 

LIST 
LOAD 
BLOCK 
B/BUF 
BLK 
SCR 
UPDATE 
FLUSH 

EMPTY-BUFFERS 



screen — ) 
screen — ) 
block - addr ) 

- n ) 

- addr ) 

- addr ) 

- ) 

- ) 

- ) 



List a disk screen. 

Load disk screen (compile or execute). 

Read disk block to memory address. 

System constant giving disk block size in bytes. 

System variable containing current block number. 

System variable containing current screen number. 

Mark last buffer accessed as updated. 

Write all updated buffers to disk. 

Erase all buffers. 



DEFINING WORDS 



: xxx 

VARIABLE xxx 
CONSTANT xxx 
CODE xxx 



( - ) 
( - ) 
( n - ) 

xxx: ( 
(n - ) 

xxx: ( 

( - ) 
( - ) 



addr ) 
n ) 



<BUILDS . . . DOES> does: ( - addr ) 



Begin colon definition of xxx. 
End colon definition. 

Create a variable named xxx with initial value n; returns address when executed. 

Create a constant named xxx with value n; returns value when executed. 

Begin definition of assembly-language primitive operation named xxx. 
Used to create a new defining word, with execution-time "code routine" for this data 
type in assembly. 

Used to create a new defining word, with execution-time routine for this data type in 
higher-level Forth. 



VOCABULARIES 

CONTEXT 
CURRENT 
FORTH 
EDITOR 
ASSEMBLER 
DEFINITIONS 
VOCABULARY xxx 
VLIST 



addr ) 
ci d r* J 



- ) 

- ) 

- ) 

- ) 

- ) 

- ) 



Returns address of pointer to context vocabulary (searched first). 

Returns address of pointer to current vocabulary (where new definitions 

Main Forth vocabulary (execution of FORTH sets CONTEXT vocabulary). 

Editor vocabulary; sets CONTEXT. 

Assembler vocabulary; sets CONTEXT. 

Sets CURRENT vocabulary to CONTEXT. 

Create new vocabulary named xxx. 

Print names of all words in CONTEXT vocabulary. 



MISCELLANEOUS AND SYSTEM 



( ( - ) Begin comment, terminated by right paren on same line; space after (. 

FORGET xxx ( - j Forget all definitions back to and including xxx. 

ABORT ( - ) Error termination of operation. 

'xxx ( - addr ) Find the address of xxx in the dictionary; if used in definition, compile address. 

HERE ( - addr ) Returns address of next unused byte in the dictionary. 

PAD ( — addr ) Returns address of scratch area (usually 68 bytes beyond HERE). 

IN ( - addr ) System variable containing offset into input buffer; used, e.g., by WORD. 

SP@ ( — addr ) Returns address of top stack item. 

ALLOT ( n — ) Leave a gap of n bytes in the dictionary. 

( n — ) Compile a number into the dictionary. 



Forth Interest Group, P.O. Box 1105, San Carlos, CA 94070 



FORTH HANDY REFERENCE 



Stack inputs and outputs are shown; top of stack on right. 
This card follows usage of the Forth Interest Group 
(S.F. Bay Area); usage aligned with the Forth 78 
International Standard. 
For more info: Forth Interest Group 

P.O. Box 1105 
San Carlos, CA 94070. 



Operand key: n, n1, . 

d, dl. . 
u 

addr 
b 
c 
f 



16-bit signed numbers 
32-bit signed numbers 
16-bit unsigned number 
address 
8-bit byte 

7-bit ascii character value 
boolean flag 



STACK MANIPULATION 



DUP 

DROP 

SWAP 

OVER 

ROT 

-DUP 

>R 

R> 

R 



( 



) 



( 



n — n n 

n - ) 
( n1 n2 - n2 n1 ) 
( n1 n2 - n1 n2 n1 
( n1 n2 n3 - n2 n3 
( n - n ? ) 
(n - ) 
( - n ) 
( - n ) 



Duplicate top of stack. 

Throw away top of stack. 

Reverse top two stack items. 
) Make copy of second item on top. 
n1 ) Rotate third item to top. 

Duplicate only if non-zero. 

Move top item to "return stack" for temporary storage (use caution). 
Retrieve item from return stack. 
Copy top of return stack onto stack. 



- 

- 



NUMBER BASES 

DECIMAL ( 



HEX 
BASE 



- ) 



( - ) 
( - addr ) 



Set decimal base. 

Set hexadecimal base. 

System variable containing number base. 



ARITHMETIC AND LOGICAL 



+ 

D+ 



/ 

MOD 
/MOD 
•/MOD 
V 

MAX 

MIN 

ABS 

DABS 

MINUS 

DMINUS 

AND 

OR 

XOR 



( n1 n2 - sum ) 
( d1 d2 - sum ) 
( n1 n2 - diff ) 
( n1 n2 - prod ) 
( n1 n2 - quot j 
( n1 n2 -* rem ) 
( n1 n2 — rem quot ) 
( n1 n2 n3 - rem quot ) 
( n1 n2 n3 - quot ) 
( n1 n2 — max ) 
( n1 n2 — min ) 
( n — absolute ) 
( d — absolute ) 
( n - -n ) 

( d - -d ) 

( n1 n2 - and ) 
( n1 n2 - or ) 
( n1 n2 - xor ) 



COMPARISON 



< 


( n1 n2 - f ) 


> 


( ni n2 - f ) 




( nl n2 - f ) 


0< 


( n - f ) 


0= 


( n - f ) 


MEMORY 




@ 


( addr - n ) 


! 


( n addr - ) 


C@ 


( addr - b ) 


C! 


( b addr - ) 


? 


( addr — ) 


+! 


( n addr - ) 


CMOVE 


( from to u — 


FILL 


( addr u b - ) 


ERASE 


( addr u -* ) 


BLANKS 


( addr u - ) 



CONTROL STRUCTURES 

DO . . . LOOP do: ( end+1 start 

I ( - index ) 

LEAVE ( - ) 

DO . . . +LOOP do: ( end+1 start 

-Hoop: ( n - ) 
IF . . . (true) . . . ENDIF if: ( f - ) 
IF . . . (true) . . . ELSE if: ( f - ) 

. . .(false). . .ENDIF 
BEGIN . . . UNTIL . until: ( f - ) 
BEGIN . . . WHILE while: ( f - ) 

. . . REPEAT 



- ) 



- ) 



Add double-precision numbers. 
Subtract (n1-n2). 
Multiply. 
Divide (n1/n2). 

Modulo {i.e. remainder from division). 
Divide, giving remainder and quotient. 

Multiply, then divide (n1*n2/n3), with double-precision intermediate. 

Like */MOD, but give quotient only. 

Maximum. 

Minimum. 

Absolute value. 

Absolute value of double-precision number. 
Change sign. 

Change sign of double-precision number. 

Logical AND (bitwise). 

Logical OR (bitwise). 

Logical exclusive OR (bitwise). 



True if n1 less than n2. 

True if n1 greater than n2. 

True if top two numbers are equal. 

True if top number negative. 

True if top number zero (i.e., reverses truth value). 



Replace word address by contents. 
Store second word at address on top. 
Fetch one byte only. 
Store one byte only. 
Print contents of address. 

Add second number on stack to contents of address on top. 
Move u bytes in memory. 

Fill u bytes in memory with b, beginning at address. 

Fill u bytes in memory with zeroes, beginning at address. 

Fill u bytes in memory with blanks, beginning at address. 



Set up loop, given index range. 
Place current index value on stack. 
Terminate loop at next LOOP or +LOOP. 

Like DO . . . LOOP, but adds stack value (Instead of always '1') to index. 

If top of stack true (non-zero), execute. (Note: Forth 78 uses IF . . . THEN.] 
Same, but if false, execute ELSE clause. (Note: Forth 78 uses IF . . . ELSE . . . THEN.) 

Loop back to BEGIN until true at UNTIL (Note: Forth 78 uses BEGIN . . . END ] 
Loop while true at WHILE; REPEAT loops unconditionally to BEGIN. 
(Note: Forth 78 uses BEGIN . . . IF . . . AGAIN ] 



! . 



the documentation 
"Going Forth" is: 



on Fig-Forth 1.4 (Calfee) 



Here is 
The address for 
Creative Solutions 
14625 Tyneuiick Terrace 
Silver Springs MD. 

This stuff doesn't seem to cover the editor, so I'm sendin 9 
a Xerox of the paper stuff. The editor is pretty simple, just 
whatever you do don't hit RETURN. Ed R°tberg £as 
(less lethal) version. You might try him at 745-1090 (Videa) 
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GRAPHICS and CONTROLLER words 



PADDLE 1-1 
PTRIO 1-1 



STICK 



1-1 



STRIO 



1-1 



GRAPHICS 1-0 
GR. 



<n> 



COLOR 

C. 



<x> <y> PLOT 

PL 



1-0 



2-0 



<*> <y> DRAWTO 2-0 

DR. 



<x> <y> POSITION 2-0 

P03. 



PUT 



1-0 



GET 



0-1 



<x> <y> LOCATE 



2-1 



<n> Cc> <1> SE. 3-0 

SETCOLOR 



Cft? <.p> <d> <v> 

SOUND 
SO. 



4-0 



. c 



PLAYER/MISSILE Graphics 



n=0~7 Reads paddle <n>. Value is O-FF 

n-0~7 Reads paddle trigger button <n> 
O-pressedi 1 =no t pressed. 

n=0-3 Reads joystick <n>. Lower 4 bits 
represent 4 directions. (0=0N l-OFF) 
D3-right, D2-left, Dl~down, DO-up 



n=0-3 Reads joystick <n> trigger button 
Oppressed/ l=not pressed 



Open screen in graphics mode <n> (BASIC 
mode #, NOT ANTIC). Add 16 (dec. ) to 
eliminate split screen. Add 32 (dec. ) 
to prevent clearing screen 

Set "color" (pixel data) for subsequent 
PLOT or DRAWTO. 



Plot a point at (<x>, < 
(0*0) is upper left corner, 
reference manual for limits 
modes. 



screen. 
See BASIC 
in particular 



Draw a line from current position to 
(<x>, <y>). 

Set current position to ( <x>, <y> ) . Does 
not plot, used with PUT, GET. 



Put the value <n> at current position. 
Current <x> is then incremented. 

Get the value of pixel data at current 
position. Current <x> is then incremented 



Same as <x> <y> POS. GET 



Set color register <n> to color <c>> 
luminance <1>. 



Set sound channel <n> to pitch <p>, 
"distortion" <d># and volume <y> 
Consult BASIC reference manual for 
further info. In general, storing to 
F1AUD, C1AUD, etc. will be easier. 



<n> 



PLAYER 1-0 



PBASE constant 



Set up player-missile graphics with <n> 
(n=l or 2) vertical line resolution. 

Returns base address of player/missile 
DMA area. This is set by GR. , and changes 
with different modes. 



<x> <n> HPOS! 



2-0 



n=0-7 Set PLAYER/MISSILE <n> horizontal 
position to <x>. MISSILE 0 = PLAYER 4 etc 



n 



<x> <n> SIZE! 



c 



0 



a- 

■ 
u 
o 
o 



n=0-4 Set size of PLAYER <n> < all 
if n=4 > to <x>. x = l ~> double size. 
x=3 => quad size. 



MISSILES 



<*> <n> COLPM! 2-0 



n~0-3, x =0-2 54 step 2 

Set color of PLAYER /MISSILE <n> to <x>. Note 
that MISSILE <n> is same color as PLAYER <n> 
unless "fifth player enable" is selected. 
( see PRIOR in hardware manual ) 



PRIOR byte 

var iab le 



VDELAY byte 

var iab 1 e 



You should store the desired priority value 
here. Consult the hardware manual for detail 

You should store the "vertical delay" bits 
here. This is only needed if single line 



CIO words 



n 



IOCS 



1-0 



CIO 



0-0 



ICDNO 
ICCOM 
ICSTA 
ICBAL 
ICBLL 
I1CAX 
I2CAX 

ICPTL 



<n> 



AC 10 



1-0 



CIOA 



0-1 



<2> <1> <d> OPEN 3-0 



CLOSE 



0-0 



positioning is needed with double line graphics 
resolution. Consult the hardware manual. 



n=Q-7 Set "current" IOCS to <n>. IOCB 0 is 
normally open to E: and should not be 
changed. IOCB 1 is used by GRAPHICS commands 
and should be restored before using them, 
(ed. note.- I know that this should have been 
IOCB 6t and that words shouldn't make such 
assumptions. I didn't write this stuff, I'm 
just documenting what exists. ) 



Calls CIO. Assumes that " <n> IOCB " has been 

done, and that I0C3 n is correctly set up. 

You should carefully read the 0. S. manual. 

The following "constants" will refer to the 

"current" IOCB: 

Device # in HATABS. (byte) 

Command (byte) 

Status (byte) 

Buffer Address (word ) 

Buffer Length (word) 

AUX1 (byte) 

AUX2 (byte) (note: these are odd to allow 
use with fixed-length-name FORTHs) 
"put-byte" address (word) (used by BASIC/ 
shun like plague) 



Call CIO with acc 
ICBLL-0 



n. Normally used with 



Call CIO and put returned acc 
Normally used with ICBLL=0 



on stack. 



Open current IOCB with AUX1=<1>, AUX2=<2> 
<d> pointing to d vc : f i 1 e. e x t. <d> should 
be just a pointer (no count) and string 
should be terminated with non-alphanumeric. 



Close the current IOCB. One of the quickest 
ways to hang FORTH is to type CLOSE without 
previously typing <n> IOCB. This closes 
IOCB Oi then returns to the outer interpreter 
which attempts to read from IOCB 0. The 
resulting error message also tries to get out 
via IOCB 0. 



PUT 



1 — o 



Do a "out character" with char=<n> 



r 



SI 



C 



E 
c 



01 

c 

0 
o 



6 



GET 



0-1 



Get one character from current IQCB, returning 
character on stack. 



c 
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4 Disk Block Numbering 

+ + + + + 

1 0 ! TYP { DRV ! BLOCK ! 
+ + + + + 

i o « r> « 11 « 



: l 
+ — 



bits 



Where: 



TYP = 



0 
1 
2 
3 



(add 

< " 



0000 
2000 
4000 
6000 



) 
) 
) 
) 



> 810 type 5 1/4" single dens. 

> 815 or 8" double dens. 

> 8" single dens. DEC interleave 
8" 11 " non-interleaved 



•> 



DRV • 



0 


(add 


0000 


) 


--> 


Dr i ve 


1 


1 


( " 


0800 


) 


-> 


it 


2 




< " 


1000 


) 


-> 


it 


3 


3 


( " 


1800 


) 


-> 


it 


4 



Dictionary Entries 

Fig t. 3 and earl ier 
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cnt 
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name 
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+- 



LFA 

(link) 
CFA 



I 

-+ 



>code 



+ 

! PFA 



I 

! 



params : 



i 

+■ 



i 



Fig 1.4 
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